NAV

DEPRECATED

Deprecated APIs.

API REFERENCE

GENERAL

Introduction

SAP Concur APIs allow clients or partners to access data and functions within the SAP Concur product ecosystem. Through the use of these exposed endpoints and functions you can solve a vast array of different business issues and reporting needs such as:

How to Use the APIs

SAP Concur APIs are accessed via an endpoint or URL. For some of our APIs the endpoint will accept parameters that will help refine the results being returned or allow for the insertion or update of data in the SAP Concur system.

Most of the SAP Concur APIs support four different types of requests:

SAP Concur also supports an alternative type of API referred to as a Callout. The Callout is a pre-configured step or condition that triggers SAP Concur to make a call out to your app to facilitate some sort of business transaction.

Explore the APIs

For the basic information on the APIs and what they do, you can check out the Swagger docs in API Explorer. Need more in-depth information? You can find information on each API using the links on the left side of the page. Finally, there are some Integration Guides that describe specific workflows. Even if none of them maps to your use case, they’re a good way to learn how to work with the SAP Concur APIs.

Resources

The information in these overviews will provide insight into what to expect during the certification process:

NOTE: These do not apply to a Triplink app integration.

HTTP Status Codes

Successful Requests

The web services return a HTTP 2xx response code when the request was successful.

HTTP Success Codes:

Success Code Message Description
200 OK The request was received successfully.

Failed Requests

The web service should return a response within 60 seconds. If the request times out without a response, the application should wait for 5 minutes then retry the request.

The web service returns a 4xx or 5xx HTTP response code when there are any errors and will include the following elements:

Element Description
StatusCode The HTTP error code.
Content A parent element that contains an Error child element.

Error elements

Element Description
Message The error message.
Server-Time The time the error was generated, based on the SAP Concur server's time zone.
Id The ID of the error within Concur.

Refer to the individual function documentation for function-specific error formats.

HTTP Error Codes

The full list of possible HTTP error codes can be found here. The table below provides additional details for commonly encountered error codes.

Error Code Message Description
400 Bad Request This response is returned if any of these conditions is true:

* The specified URI is invalid.
* The request is not formatted correctly.
* The request is missing a required field.
* The number of requests received exceed the request limit.
* The request encountered a database deadlock. In this case, the developer should resend the request a short time later.
* This error can be received if Chunked Transfer-Encoding is enabled by the developer's web server. Concur does not support Chunked Transfer-Encoding.

Attendee Web Service:

* The batch type parameter is not included on the URI of batch operations.
* The request contains 0 attendees.
* The request contains over 1000 attendees.

Imaging Web Service:

* The barcode or reportId is missing.

Purchase Order Web Service:

* The request contains 0 purchase orders.
* The request contains over 1000 purchase orders.

List Item Web Service:

* The request contains 0 list items.
* The request contains over 1000 list items.

Payment Batch File:

* The Batch ID specified in the URI is invalid.

Trip Approval:

* The request contains 0 itineraries.

User Web Service:

* The request contains 0 users.
* The request contains over 1000 users.
401 Unauthorized The Authorization header is not included in the request.
403 Forbidden This response is returned if any of these conditions is true:

* The Authorization header is included but it fails validation. This can happen if the OAuth consumer does not have access to the Concur product required by the web service.
* The partner application associated with the oauth_consumer_key has not been allowed access to the requested company.
* The Oauth token has expired or been revoked.
404 Not Found Extract Web Service: The Definition ID or Job ID specified in the URI is invalid.

Imaging Web Service: No image was found for the specified report Id or barcode.

Itinerary Web Service: The Trip ID or Booking ID specified in the URI is invalid.

Payment Batch Web Service: The Batch ID specified in the URI is invalid.
409 Conflict Extract Web Service: A job for the specified definition is already queued or running.
429 Too Many Requests This response is returned when services are overloaded either with too many requests from a single source or too many requests in aggregate. When this happens slow the rate of requests.
500 Internal Server Error/Not Closed Expense Report Web Service: This response is returned when the system is unable to calculate an exchange rate for a posted expense report entry.
Payment Batch Web Service: The specified batch could not be closed.
503 Service Unavailable This response is returned when the web service is down for maintenance. The partner application should sleep for 5 minutes then retry the request. If the request continues to fail after a few retries, the developer should contact concurconnecttech@concur.com.

Locale Codes

All Concur customers have the following locale set in their entities by default. This is the only locale that is available for all clients.

Default Locale

Locales Code
English (United States) en_US

Customers can request to have additional locales added to their entity if necessary. The following list includes all supported locales.

All Supported Locales Code
Bulgarian (Bulgaria) bg_BG
Chinese (China) zh_CN
Chinese (Hong Kong) zh_HK
Chinese (Taiwan) zh_TW
Croatian (Croatia) hr_HR
Czech (Czech Republic) cs_CZ
Danish (Denmark) da_DK
Dutch (Belgium) nl_BE
Dutch (Netherlands) nl_NL
English (Australia) en_AU
English (Canada) en_CA
English (India) en_IN
English (Ireland) en_IE
English (New Zealand) en_NZ
English (South Africa) en_ZA
English (United Kingdom) en_GB
English (United States) en_US
Finnish (Finland) fi_FI
French (Belgium) fr_BE
French (Canada) fr_CA
French (France) fr_FR
French (Luxembourg) fr_LU
French (Switzerland) fr_CH
German (Austria) de_AT
German (Germany) de_DE
German (Luxembourg) de_LU
German (Switzerland) de_CH
Hungarian (Hungary) hu_HU
Indonesian (Indonesia) id_ID
Italian (Italy) it_IT
Italian (Switzerland) it_CH
Japanese (Japan) ja_JP
Korean (North Korea) ko_KP
Korean (South Korea) ko_KR
Norwegian (Norway) no_NO
Polish (Poland) pl_PL
Portuguese (Brazil) pt_BR
Romanian (Romania) ro_RO
Russian (Russian Federation) ru_RU
Slovak (Slovakia) sk_SK
Spanish (Argentina) es_AR
Spanish (Bolivia) es_BO
Spanish (Chile) es_CL
Spanish (Colombia) es_CO
Spanish (Costa Rica) es_CR
Spanish (Dominican Republic) es_DO
Spanish (Ecuador) es_EC
Spanish (El Salvador) es_SV
Spanish (Guatemala) es_GT
Spanish (Honduras) es_HN
Spanish (Mexico) es_MX
Spanish (Nicaragua) es_NI
Spanish (Panama) es_PA
Spanish (Paraguay) es_PY
Spanish (Peru) es_PE
Spanish (Puerto Rico) es_PR
Spanish (Spain) es_ES
Spanish (Uruguay) es_UY
Spanish (Venezuela) es_VE
Swedish (Sweden) sv_SE
Thai (Thailand) th_TH
Turkish (Turkey) tr_TR

Spend Category Codes

The following table lists Spend Category codes that are used in several of the Concur APIs.

Code Name
ADVTG Advertising/Marketing
AIRFE Airline Fee
AIRFR Airfare
CARRT Car Rental
COCAR Company Car - Fixed Expense
COCRM Company Car Mileage
COMPU Computer
ENTER Entertainment
FEESD Fees/Dues
GASXX Gas
GOODW Goodwill
GRTRN Ground Transportation
LODGA Lodging - Track Hotel Spending
MEALS Meal
MEETG Meetings
OFFIC Office
OTHER Other
PRCAR Personal Car - Fixed Expense
PRCRM Personal Car Mileage (Expense Professional), Car Mileage (Expense Standard)
PRKNG Personal Car - Parking Expense
RAILX Rail
SHIPG Shipping
SUBSC Subscription/Publication
TELEC Telecom
TRADE Trade/Convention
TRAIN Training

AUTHENTICATION

Authentication

Special Note (Please Read First)

If you are an existing partner with an existing app, please read both the Migration to Oauth2 Tokens and Getting Started documentation first. If you have any questions, please contact your Partner Enablement team representative before proceeding.

Note: The Pre-2017 Authorization (Deprecated) documentation be found here

Access Tokens

The Oauth2 service generates access tokens for authenticated users, applications or companies. The token returned in the Oauth2 response can be used to access protected resources on SAP Concur services.

The Oauth2 response can, depending on grant type contain these values:

Name Type Format Description
expires_in string - The lifetime in seconds of the access token
scope string - The scope of the access token as granted to the client application
token_type string - The type of token returned. Value will be Bearer
access_token string - Token used to access protected resources of SAP Concur services.
refresh_token string - Refresh token required to request a new access token for a given user.
geolocation string - The base URL for where the user profile lives. See base URI for usage.
id_token string - The OCID Token in the JSON Web Token (JWT) format that describes the user or company

Token Response

HTTP/1.1 200 OK
Content-Type: application/json
Date: date-requested
Content-Length: 3397
Connection: Close
{
  "expires_in": "3600",
  "scope": "app-scopes",
  "token_type": "Bearer",
  "access_token": "access_token",
  "refresh_token": "refresh_token",
  "id_token": "ocid_token",
  "geolocation": "https://us.api.concursolutions.com"
}

Obtaining a token

You can obtain a token for three different types of principals in the SAP Concur universe.

Token Lifetime

An accessToken has a one hour lifetime.

In order to obtain a token, the client application needs to call the Oauth2 endpoint using various grants depending on the authentication scenarios required. The full list of supported scenarios is provided below:

Refreshing a token

The refresh grant is used to refresh an access_token that has expired. This grant can be used anytime a refresh_token is returned in the response of another grant request. No user interaction is required.

Token Lifetime

A refresh token has a six month lifetime. If the refresh token expires, the client application must reinitiate the authorization process. When a refresh token is used to request a new access token, both a new access token as well as a new refresh token are returned in the response. This token can change even if most of the time, this value is the same. Client applications should treat all returned refresh tokens as new tokens and overwrite the stored tokens with the new token from the response.

It is recommended that the client application use the refresh grant to request a new access token as the initial step of accessing protected resources of SAP Concur services.

Refreshing the token

To request a new access token using a valid refresh token, use the Oauth2 /token endpoint. Use the application/x-www-form-urlencoded content type.

POST /oauth2/v0/token

Post Body

Name Type Format Description
client_id string UUID Required The client applications client_id supplied by App Management
client_secret string UUID Required The client applications client_secret supplied by App Management
refresh_token string UUID Required An existing valid refresh token to be used to request a new access token
scope string - Optional The client applications list of scopes
grant_type string - Required The grant type instructs the Oauth2 service how to process the request. For refresh token, the value must be refresh_token

Request

POST /oauth2/v0/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: us.api.concursolutions.com
Connection: close
Content-Length: 437

POST BODY
client_id=your-client_id
&client_secret=your-client_secret
&grant_type=refresh_token
&refresh_token=valid-refresh_token
&scope=app-scope

Response

HTTP/1.1 200 OK
Content-Type: application/json
Date: date-requested
Content-Length: 3397
Connection: Close
{
  "expires_in": "3600",
  "scope": "app-scopes",
  "token_type": "Bearer",
  "access_token": "access_token",
  "refresh_token": "refresh_token",
  "id_token": "ocid_token",
  "geolocation": "https://us.api.concursolutions.com"
}

When the token has been refreshed, store the geolocation and the refresh token as they may have changed. On subsequant calls, use the last received golocation and refresh token.

Revoking a token

All refresh_tokens associated to a user for an application can be revoked by calling the https://us.api.concursolutions.com/app-mgmt/v0/connections endpoint with a DELETE action. You have to provide the User's accessToken in the Authorization Header as Authorization: Bearer <access_token>.

DELETE https://us.api.concursolutions.com/app-mgmt/v0/connections

Request

DELETE https://us.api.concursolutions.com/app-mgmt/v0/connections
Authorization: Bearer {token}

Response

HTTP/1.1 200 OK

Managing tokens

Refresh Tokens are strings that allow your application to obtain a fresh accessToken on behalf of a user to access SAP Concur APIs. The exact format of the string can change, but may look similar to the following:

e013335d-b4ce-4c43-a7e4-b67abc1adcb0

It is highly recommended that you store Refresh Tokens together with your user's authorization metadata in your application every time you obtain a new refreshToken as they might change depending on different scenarios.

FOR APP CENTER AND SUPPLIER PARTNERS supporting all geolocations, storing the authorization metadata, including the geolocation are REQUIRED.

Base URIs

When making API calls, the appropriate base URI should be used. There are three different scenarios: 1. Obtaining a token for a user. 2. Refreshing a token. 3. Calling other APIs.

The base URI for obtaining a token will leverage your application's geolocation. The base URI for refreshing tokens and all other API calls will leverage the token's geolocation.

Base URIs for Obtaining a Token

When your application is created, you will be provided with a client ID, secret and geolocation. When obtaining a token, your application should use the base URI for the geolocation in which your application exists.

There are two endpoints for each geolocation - one is the default (used for server-side calls) and the other should be used for client-side calls.

The full list of available token geolocations is available on the Base URIs page.

When obtaining the token, the token's geolocation will be included in the response. The token's geolocation should be stored along with the token. The Developer's app will then be able to make subsequent calls using the token and the correct end points based on the token's GEO location.

Base URIs for All Other Calls

When refreshing a token or when calling any other APIs, the token's geolocation should be used as the base URI.

Note: Client-side calls should use the www- variant of the base URI.

For example: When obtaining a token, if the response was the below:

HTTP/1.1 200 OK
Content-Type: application/json
Date: date-requested
Content-Length: 3397
Connection: Close
{
  "expires_in": "3600",
  "scope": "app-scopes",
  "token_type": "Bearer",
  "access_token": "access_token",
  "refresh_token": "refresh_token",
  "id_token": "ocid_token",
  "geolocation": "https://us.api.concursolutions.com"
}

When then calling the receipts API to post a receipt, your request should be made to https://us.api.concursolutions.com (if server side) or https://www-us.api.concursolutions.com (for clients).

ID Token

Authentication service will return an OPENID compatible ID token with every token request. This id_token is primarily used to describe information about a user or a company. You can obtain the userId from this token.

Sample id_token:

{
  "aud": "e010e25d-b4ce-4ce3-a7e4-b670cb1adcb0",
  "concur.profile": "https://us.api.concursolutions.com/profile/v1/principals/76459ad3-f77b-4d98-a21a-55333c9179f0",
  "concur.version": 2,
  "concur.type": "user",
  "sub": "76459ad3-f77b-4d98-a21a-55333c9179f0",
  "iss": "https://us.api.concursolutions.com",
  "exp": 1485485529,
  "nbf": 1485481929,
  "at_hash": "351515a6482f4ee1",
  "iat": 1485481929
}

Verifying an id_token

The Authentication service exposes JWKs that can be used to validate the id_token in the form of a JWT. Validating a JWT is described in detail in RFC 7519 - sec 7.2

This is the link to the SAP Concur JSON Web Key for Oauth2. https://www-us.api.concursolutions.com/oauth2/v0/jwks

Authorization grant

The authorization grant is the regular 3-legged oauth2 grant and is defined in detail in RFC6749 sec-4.1. This grant requires the user to explicitly authenticate themselves and authorise the application initiating the grant.

The users must be able to authenticate themselves via an SAP Concur username & password. Users will be challenged to login by an Oauth2 HTML page.

Who should use it * 3rd party "partner" websites - or - * non-SAP Concur Applications - & - * Applications that need explicit user authentication & authorization - & - * Applications that can securely store a code, access_token & refresh_token

Grant details

Note that the grant type must be accessed using the www- version of the API Gateway in order to avoid certificate issues with some browsers. (ex: https://www-us.api.concursolutions.com instead of https://us.api.concursolutions.com)

GET /oauth2/v0/authorize

Name Type Format Description
client_id string UUID Applications client_id supplied by App Management
redirect_uri string - The redirect URI for your application to continue with the Oauth2 flow
scope string - List of scopes that application is asking for
response_type string - code
state string -

With this grant, the user has two authentication options: 1. Username and password 2. One-time link using a verified email address

With both options, once the user is successfully authenticated and the user authorizes your application, the user will be redirected to the redirect_URI specified in the initial /authorize call with a temporary token appended.

<redirect_uri>?geolocation=<token_geolocation>&code=<token>

If the user is not successfully authenticated or does not authorize the scopes for your application, an error code and description will be appended to the redirect URI. Please refer to the Response Codes section for more information.

Your application must then exchange the temporary token for a long-lived token using the below.

POST /oauth2/v0/token

Name Type Format Description
client_id string UUID Applications client_id supplied by App Management
client_secret string UUID Applications client_secret supplied by App Management
redirect_uri string - The redirect_uri that is registered for the application
code string UUID The authorization code provided by Auth
grant_type string - authorization_code

Password grant

The Password grant can be used when there is a trust relationship between the user and the application. There are two credential types allowed with Password Grant:

  1. "Password": with this credential type, the application either already has the user's credentials or can obtain the user's credentials by directly interacting with the user.
  2. "AuthToken": This credential type is used for connections from the App Center. For App Center partners and TripLink suppliers, please refer to the certification documentation for more information.

Post Body

Name Type Format Description
client_id string UUID Applications client_id supplied by App Management
client_secret string UUID Applications client_secret supplied by App Management
grant_type string - Specify which grant type you expect the oauth2 service to process. for password grant, the value is password
username string - specify the username or userId
password string - specify the user's password
credtype string - The credtype signifies to oauth2 which credential set is being submitted in the request. There are two supported values: authtoken and password. For connections from the App Center, use authtoken. if omitted, oauth2 will assume the type is password.

Request

POST /oauth2/v0/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: us.api.concursolutions.com
Connection: close
Content-Length: 175

POST BODY
client_id=your-client_id
&client_secret=your-client_secret
&grant_type=password
&username=username
&password=password

Response

HTTP/1.1 200 OK
Content-Type: application/json
Date: date-requested
Content-Length: 3397
Connection: Close
{
  "expires_in": "3600",
  "scope": "app-scopes",
  "token_type": "Bearer",
  "access_token": "access_token",
  "refresh_token": "refresh_token",
  "id_token": "ocid_token",
  "geolocation": "https://us.api.concursolutions.com"
}

example bad login

{
  "error": "invalid_grant",
  "error_description": "Incorrect Credentials. Please Retry",
  "code": 5
}

Client Credentials grant

Use the application/x-www-form-urlencoded content type.

POST /oauth2/v0/token

Post Body

Name Type Format Description
client_id string UUID Required Applications client_id supplied by App Management
client_secret string UUID Required Applications client_secret supplied by App Management
grant_type string - Required Specify which grant type you expect the oauth2 service to process. For client_credentials grant, the value is client_credentials

Request

POST /oauth2/v0/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: us.api.concursolutions.com
Connection: close
Content-Length: 127

POST BODY
client_id=your-client_id
&client_secret=your-client_secret
&grant_type=client_credentials

Response

HTTP/1.1 200 OK
Content-Type: application/json
Date: date-requested
Content-Length: 1626
Connection: Close
{
  "expires_in": "3600",
  "scope": "app-scopes",
  "token_type": "Bearer",
  "access_token": "access_token",
  "geolocation": "https://us.api.concursolutions.com"
}

One Time Password grant

The One-time Password grant type leverages email, phone (text messaging), instant messaging and similar systems to provide per user access tokens to client applications. This grant type requires the following steps:

  1. The calling application calls the OAuth2 service specifying the otp grant type along with required parameters.
  2. The OAuth2 service generates a one time token which it sends through the messaging mechanism chosen by the application.
  3. The user retrieves the token and presents it to the application. The means of having this presented to the application is the responsibility of the application.
  4. The application presents this one-time token to the OAuth2 service via the token endpoint.

Request a one-time token to be sent to the user

Use the application/x-www-form-urlencoded content type.

POST /oauth2/v0/otp

Post Body

Name Type Format Description
client_id string UUID Required The client_id as defined in the SAP Concur application management system.
client_secret string UUID Required The client_secret as set by the client owner in the SAP Concur application management system.
channel_handle string - Required The location (email address, phone number) where the one time token should be sent. Currently, only email address is valid.
channel_type string - Required The type of messaging system to use. Currently only email is valid
name string - Optional The name of the user that appears in the email.
company string - Optional The company or application name that appears in the email.
link string - Optional The callback URL that appears in the email for users to click to complete the auth flow.

The calling application code can also append n-number of unique client defined parameters in the URI for the purpose of connecting the one time token to the application when received by the user. The names of these parameters cannot conflict with the API defined parameters.

The following are reserved words and cannot be used as client application defined parameters:

/otp: "client_id" "client_secret" "channel_type" "channel_handle"
/token: "client_id" "client_secret" "channel_type" "channel_handle" "scope" "grant_type" "otp"

If the calling application chooses to send custom parameters, all of these exact same parameters must be included in subsequent API calls to acquire the access token. In other words, the URI signature, modulo the one time token parameter itself and token service specific parameters, must match the originating URI signature.

Request

POST /oauth2/v0/otp HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Accept: application/json
Host: us.api.concursolutions.com
Connection: close
Content-Length: 437

POST BODY
client_id=your-client_id
&client_secret=your-client_secret
&channel_handle=email adress
&channel_type=valid-email
&link=https://example.com/callback

Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 22
Date: date-requested
{
  "message": "otp sent"
}

Request an access token

The One Time Password grant requires that all of the parameters, including client application defined parameters to be sent in the request body when requesting an access token. Use the application/x-www-form-urlencoded content type.

POST oauth2/v0/token

Post Body

Name Type Format Description
client_id string UUID Required The client_id as defined in the SAP Concur application management system.
client_secret string UUID Required The client_secret as set by the client owner in the SAP Concur application management system.
channel_handle string - Required The location (email address, phone number) where the one time token should be sent.
channel_type string - Required The type of messaging system to use. Currently only email is valid
scope string - The scope(s) requested by the client for the token.
grant_type string - Required The grant type being used, specifically for this approach: otp.
otp string - Required The one-time token provided as a result of the Send a one time token to the user method.

Request

POST /oauth2/v0/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: us.api.concursolutions.com
Connection: close
Content-Length: 437

POST BODY
client_id=your-client_id
&client_secret=your-client_secret
&channel_handle=email adress
&channel_type=valid-email
&scope=app_scope
&grant_type=otp
&otp=one-time-token

Response

HTTP/1.1 200 OK
Date: date-requested
Content-Length: 1490
Connection: keep-alive
{
  "expires_in": "3600",
  "scope": "app-scopes",
  "token_type": "Bearer",
  "access_token": "access_token",
  "refresh_token": "refresh_token",
  "id_token": "ocid_token",
  "geolocation": "https://us.api.concursolutions.com"
}

Response Codes

HTTP Status returned by oauth2
HTTP Status Description
200 OK - Successful call, response is in body.
400 Bad Request (error, error_description, code)
401 Unauthorized (error, error_description, code)
403 Forbidden (error, error_description, code)
404 Not Found (error, error_description, code)
500 Server Error, error message is in body.
503 Server Timed Out, error message is in body.

4xx class errors have a JSON response with the following fields

{
  "code": <number>,
  "error": <error>,
  "error_description": <error_description>,
  "geolocation": <geolocation url where user lives>
}
/authorize

If the authorization or authentication are unsuccessful, your application will receive an error code and description at the redirect_uri provided.

 error_code=<>
 &error_description=<>

In all cases, the friendly error description should be displayed to the user.

/token
Code Error Description
5 invalid_grant Incorrect credentials. Please Retry
10 invalid_grant Account is disabled. Please contact support
11 invalid_grant Account is disabled. Please contact support
12 invalid_grant Logon Denied. Please contact support
13 invalid_grant Logon Denied. Please contact support
14 invalid_grant Account Locked. Please contact support
16 invalid_request user lives elsewhere
19 invalid_grant Incorrect credentials. Please Retry
20 invalid_grant Logon Denied. Please contact support (typically due to IP restriction)
51 invalid_request username was not supplied
52 invalid_request password was not supplied
53 invalid_client company is not enabled for this client
54 invalid_scope requested scope exceeds granted scope
55 invalid_request we don't know this email
56 invalid_request otp was not supplied
57 invalid_request channel_type missing
58 invalid_request channel_handle missing
59 access_denied client disabled
60 invalid_grant these are not the grants you are looking for
61 invalid_client client not found
62 invalid_request client_id was not supplied
63 invalid_request client_secret was not supplied
64 invalid_client Incorrect credentials. Please Retry
65 invalid_request grant_type was not supplied
80 invalid_request invalid channel type
81 invalid_request bad channel handle
83 invalid_request otp not found
84 invalid_request fact verification failed
85 invalid_request otp verification failed
100 invalid_request backend does not know about this username
101 invalid_request code was not supplied
102 invalid_request redirect_uri was not supplied
103 invalid_request code is bad or expired
104 invalid_grant redirect_uri does not match the previous grant
105 invalid_grant this grant was not issued to you!
106 invalid_request refresh_token was not supplied
107 invalid_request refresh disallowed for app
108 invalid_grant bad or expired refresh token
109 invalid_request loginid was not supplied
115 invalid_request unauthenticated client will not be issued token!
117 invalid_request nonce is mandatory for this response_type
118 invalid_request display is invalid
119 invalid_request prompt is invalid
119 invalid_request prompt must be set to consent for offline_access
120 invalid_request credtype is invalid
121 invalid_request login_type is invalid
122 invalid_request proxies supplied are invalid
123 invalid_request principal is disabled
/otp
Code Error Description
16 invalid_request user lives elsewhere
57 invalid_request channel_type was not supplied
58 invalid_request channel_handle was not supplied
60 invalid_grant these are not the grants you are looking for
61 invalid_client client_id is not known to us
62 invalid_request client_id was not supplied
63 invalid_request client_secret was not supplied
80 invalid_request invalid channel type
81 invalid_request bad channel handle
82 invalid_request the number of open otp requests has been exceeded

Troubleshooting

In order to assist with troubleshooting, SAP Concur responds with a unique correlationId in the response header. The key to look for is correlationid. This unique code can be used during troubleshooting as it identifies the API call in the log files. You should record this information in your own API call logs as well so that you can pass this information on to the SAP Concur support team.

Example of the correlationid in the response:

< HTTP/1.1 200 OK
< Server: cnqr-papeete
< Date: Mon, 04 Dec 2017 22:07:05 GMT
< Content-Type: application/json
< Content-Length: 2897
< Connection: keep-alive
< Concur-Correlationid: 2803b8f8-a42b-43c2-a739-b8768e4759b8

Enterprise Business Applications

Only the Password Grant Type is available for obtaining company-level tokens.

  1. To begin the authentication flow, a Customer's SAP Concur Administrator clicks on the Connect button within the App Center listing and authorizes the partner's app. This app listing is located within customer's SAP Concur system's App Center tab.
  2. The SAP Concur authorization service will redirect the Admin to the Partner’s Landing Page. Partners should follow the App Center UX Guidelines to create a web page that listens for an HTTP GET request from SAP Concur.
  3. The redirect URI will contain an id, requestToken and userId parameters. Example: https://{partner_redirect_URI}?id=8568a4cd-8ffc-49d6-9417-be2d69aa075f&requestToken=5l85ae5a-426f-4d6f-8af4-08648c4b696b&userId=9bdded51-00b8-4f84-8bef-6d3afe727007
  4. When the Partner application receives the redirect call, the Partner should strip the id and requestToken values from the URI and use those on a Post request to the SAP Concur Authorization service to obtain the official Oauth2 Access Token and Refresh Token for the customer using the password grant. As explained in detail in this presentation, the Partner must have Data Center Geo Awareness related to the token. We currently have 3 Data Centers and the API end points change based on these Data Centers so it is imperative the proper token management is followed. Otherwise, your app will not make the correct call per Access token.
  5. An access token is valid for only one hour. The access token should be cached in memory and discarded after use.
  6. After the Admin has successfully completed the login/enrollment process, the Partner should store the following elements with the customer’s profile metadata.
    • refresh_token: (36 characters including dashes) Valid for six months from the day and time issued.
    • refresh_expires_in: This is Epoch time format, convert to UTC.
    • geolocation: To be used when making API calls on behalf of the customer.
    • id: Aka sub, is the customer’s unique identifier (UUID). It can be retrieved from the following sources:
    • From the re-direct URI as the id element.
    • By decoding the id_token returned with Access token, as the sub element. (See https://jwt.io)
  7. It is highly recommended that Partners log the following elements:
    • userId: the user who clicked on the Connect button (returned in the re-direct URI)
    • correlationid: SAP Concur responds with a unique code which identifies the API call in the log files. (returned in the response header). More details can be found here.

Learn More About Scopes

Partner Application Scope Usage

The table below lists all the possible scopes that an SAP Concur Partner Application might have access to. Please refer to the App Center Terms and Conditions and look under the "Shared Information" dialogue. Links to API endpoints that are accessible by each scope are mapped out.

Note:

Scope User Description                                       APIs
ATTEND Add, update, or deactivate attendees Attendees
BANK Employee Banking Report Details-Employee Banking
budgetitem.read Grants read access to the budget resources Budget v4
budgetitem.write Grants read and write access to the budget resources Budget v4
CCARD Credit Card Company Card Transactions, Report Details-Card Transactions
COMPD Company details Travel Profile v3 Company Details, Travel Profile v2 Custom Fields
company.read Read company profile information Profile, Company API (Profile v1)
company.write Read and update company profile information Profile, Company API (Profile v1)
CONFIG Understand how to post expense information according to your company's configuration Expense Group Configurations, Quick Expense v4
CONREQ Use your travel profile information to get or update connection requests between SAP Concur and travel reward program partners Connection Requests 3.2, Connection Requests 3.0, Connection Requests 3.1
EMERG Emergency Contact information Travel Profile v2 Emergency Contact
events.topic.read Grants read and write access to Event Topics once subscribed Event Subscription Service v4
expense.exchangerate.writeonly Create custom exchange rates Exchange Rate v4
expense.report.read Get information about expense reports Comments v4, Reports v4, Allocations v4, Expenses v4
expense.report.readwrite Read and write expense report headers Comments v4, Reports v4, Allocations v4, Expenses v4
expense.report.workflowstatus.write Approve or Send Back the Report in the workflow Comments v4, Reports v4
EXPRPT Get, add, approve, or update expense reports Allocations v3, Expense Report Entry v2, Expense Report Form Field v1.1, Expense Report Form v1.1, Expense Report Itemization v3, Expense Report Integration Status v2, Expense Report POST Exceptions v1.1, Expense Report POST Submission v1.1, Expense Report POST Workflow v1.1, Expense Reports v3, Expense Report v2, Expense Entry Itemization POST v1.1, Expense Entry Itemization v1.1, Expense Entry v1.1, Expense Entry GET 1.1, Expense Entry POST 1.1, Expense Report Header v1.1, Expense Reports List v1.1, Expense Report v1.1 Report Details, Expense Report v1.1 Locations, Expense Report v1.1 Location, Expense Report v2, Expense Report v2 Reports
EXTRCT Extract expense data Extracts v1
fiscalcalendar.read Grants read access to the fiscal calendar Budget v4
fiscalcalendar.write Grants read and write access to the fiscal calendar Budget v4
identity.user.ids.read Read user ID data Identity v4
identity.user.core.read Read user core data Identity v4
identity.user.coresensitive.read Read core sensitive data Identity v4
identity.user.enterprise.read Read user enterprise data Identity v4
identity.user.coreenterprise.writeonly Write access to all core and enterprise fields except externalID Identity v4
identity.user.externalID.writeonly Write access to externalID only Identity v4
IMAGE Add or get invoice and receipt images Receipt Image v3, Receipt Image v1
INSGHT Access itineraries and identify missing trip segments Insights-Latest Bookings, Insights-Opportunities
invoice.providerpayment.write Read access to pending payments, and write access to payment status Invoice Pay v4
INVPMT Create, Retrieve and Update for Payment Requests Invoice Payment Request v3, Invoice Retrieve Payment Request Digests v3
INVPO Create or update purchase orders Invoice Purchase Orders v3
INVTV View tax invoices and update validation status Invoice Sales Tax Validation Request v3
INVVEN Vendors search and retrieve list of vendors Invoice Vendor v3, Invoice Vendor Group Swagger, Invoice Vendor Bank Swagger
ITINER Get, add, or update travel itineraries and bookings Itinerary Web Service, Travel-Booking Resource, Itinerary Service, Travel-Trips v1.1, Travel Services, Trip Approval v1
LIST Use and update drop-down lists configured by your company List Item v3, List v1, List v1 Resource, Get List of List v1, Post New List v1, Budget v4
locate.location.read Allows the application to only to view the SAP Concur Locate user location User Location v4
locate.location.write Allows the application to write user location information using SAP Concur Locate API service User Location v4
MEDIC Medical alerts Travel Profile v2 Medical Alerts
NOTIF Receive notifications when expense reports change Event Notification Callout, Get Notification, Delete Notification, Post Notification
PASSV Passport visa information Travel Profile v2 Passport, Travel Profile v2 Visa
PAYBAT Close and export payment batches Payment Batches v1.1
purchaserequest.read Allows you to retrieve purchase requests Purchase Request v4
purchaserequest.write Allows you to create new purchase requests Purchase Request v4
quickexpense.writeonly Write quick expense Quick Expense v4
RCTIMG Add or update receipt and OCR images Receipt Image v3
receipts.read Read receipt data Receipts v4
receipts.write Read receipt data and post receipts Receipts v4
receipts.writeonly Post receipts on your behalf Receipts v4, Quick Expense v4
spend.list.delete Delete capabilities for spend lists List v4
spend.list.read Read only access to spend list and category details Reports v4, Allocations v4, Expenses v4, List v4
spend.list.write Read and write access to spend lists List v4
spend.listitem.delete Delete capabilities for spend list items List Item v4
spend.listitem.read Read only access to spend list items listItemId Reports v4, Allocations v4, Expenses v4, List Item v4
spend.listitem.write Read and write access to spend list items List Item v4
SUPSVC Get supplier data Suppliers v3
TAXINV Get or validate digital tax invoices Sales Tax Validation v3
TMCSP TMC specific information Travel Profile v2 TMC
travelallowance.allowancedays.read View the allowance days in an expense report Travel Allowance API
travel.receipts.read Read travel receipt requests Travel Receipts, Travel Receipts Sample
travel.receipts.write Post travel receipts Travel Receipts, Travel Receipts Sample
travelrequest.write Add, update, or delete travel requests Request v4
TSAI TSA information Travel Profile v2 TSA
TRVPRF Access and update Concur Travel profile information Travel Profile v2, Travel Profile v2 Resource
TRVPTS Access user balances and post travel points redemptions Travel Profile v1 Travel Points
TRVREQ Add, update, or delete authorization requests Travel Request v3
TWS Approve or reject travel itineraries Trip Approvals
UNUTX Unused tickets Travel Profile v2 Unused Tickets
USER Add or update SAP Concur user accounts User v1, User v3, User v3.1
user.read Read profile information Profile, User API (Profile v1), Comments v4, Reports v4, Allocations v4, Expenses v4, Quick Expense v4
user.write Read and update profile information Profile, User API (Profile v1)
user_read Read only access to user travel preference data User v1, User v3, User v3.1

Company Level Authentication

Company

Company is a top-level principal within Concur and you would be able to obtain an access token and a refresh token on a Company's behalf just like you would be able to with a User. Only one authorization flow is currently available for obtaining tokens for a Company, which is the Password grant using a temporary auth token received from the App Center.

Obtaining an auth token

To begin the authentication flow for a company, one must first obtain a temporary auth token through AppCenter's interface. AppCenter will request for a temporary auth token and hand it off to the partner, who will then in turn use Password grant to exchange the temporary auth token for a full access token and refresh token for the company.

Auth tokens are valid only for 12 hours. Partners have 12 hours to exchange the auth token for a refresh and access token, and can use this auth token multiple times within the 12 hours in case of network failure.

This auth flow diagram describes this handshake:

Company Authentication Flow Sequence Diagram

Company Authentication Flow Sequence Diagram

AppCenter will call this endpoint to obtain an authToken.

POST /profile-service/v1/keys/principals/<companyId>/authtoken/

Sample Curl:

curl -E appcenter.p12:. -H 'concur-correlationid: githbuwiki' -XPOST https://us.api.concursolutions.com/profile-service/v1/keys/principals/08BCCA1E-0D4F-4261-9F1B-F778D96617D6/authtoken/
200 OK
{
  "status": "PASS",
  "code": 0,
  "errormsg": "",
  "token": "<authToken>"
}

AppCenter redirects User to Client's auth handler URI (Connect URL) and passing in the authToken

301 Redirect https://client.app.url?id=$company_uuid&requestToken=$request_token&userID=$user_uuid

At this point, the user should be prompted to sign in to your application. If the user doesn't not have account, the user should have the ability to create one. For applications that have user read scope, the User UUID can be used to pre-populate the account creation forms. Please see the App Center User Experience guidelines for more information.

Client app calls Oauth2 password grant to get an access token for the company

Name Type Format Description
client_id string UIID Applications client_id supplied by App Management
client_secret string UUID Applications client_secret supplied by App Management
grant_type string - Specify which grant type you expect the oauth2 service to process. For password grant, the value is password
username string - specify the companyId to be used in the password grant request. The id above.
password string - specify the authToken to be used in the password grant request. The requestToken above.
credtype string - The credtype signifies to oauth2 which credential set is being submitted in the request. The value: authtoken.

Example

Request

POST /oauth2/v0/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: us.api.concursolutions.com
Connection: close
Content-Length: 175

client_id=your-client_id
&client_secret=your-client_secret
&grant_type=password
&username=<companyId>
&password=<authtoken>
&credtype=authtoken

Response

Success

HTTP/1.1 200 OK
Content-Type: application/json
Date: date-requested
Content-Length: 3397
Connection: Close
{
  "expires_in": "3600",
  "scope": "app_scopes",
  "token_type": "Bearer",
  "access_token": "access_token",
  "refresh_token": "refresh_token",
  "geolocation":"https://us.api.concursolutions.com"
}

Failure

{
  "error": "invalid_grant",
  "error_description": "Incorrect Credentials. Please Retry",
  "code": 5
}

Response Codes

HTTP Status Code returned by oauth2
HTTP Status Code Description
200 OK - Successful call, response is in body.
400 Bad Request (error, error_description, code)
401 Unauthorized (error, error_description, code)
403 Forbidden (error, error_description, code)
404 Not Found (error, error_description, code)
500 Server Error, error message is in body.
503 Server Timed Out, error message is in body.

4xx class errors have a JSON response with the following fields

{
  "code": "<number>",
  "error": "<error>",
  "error_description": "<error_description>"
}
/token
Code Error Description
5 invalid_grant Incorrect credentials. Please Retry
10 invalid_grant Account is disabled. Please contact support
11 invalid_grant Account is disabled. Please contact support
12 invalid_grant Logon Denied. Please contact support
13 invalid_grant Logon Denied. Please contact support
14 invalid_grant Account Locked. Please contact support
16 invalid_request user lives elsewhere
19 invalid_grant Incorrect credentials. Please Retry
51 invalid_request username was not supplied
52 invalid_request password was not supplied
53 invalid_client company is not enabled for this client
54 invalid_scope requested scope exceeds granted scope
55 invalid_request we don't know this email
56 invalid_request otp was not supplied
57 invalid_request channel_type missing
58 invalid_request channel_handle missing
59 access_denied client disabled
60 invalid_grant these are not the grants you are looking for
61 invalid_client client not found
62 invalid_request client_id was not supplied
63 invalid_request client_secret was not supplied
64 invalid_client Incorrect credentials. Please Retry
65 invalid_request grant_type was not supplied
80 invalid_request invalid channel type
81 invalid_request bad channel handle
83 invalid_request otp not found
84 invalid_request fact verification failed
85 invalid_request otp verification failed
100 invalid_request backend does not know about this username
101 invalid_request code was not supplied
102 invalid_request redirect_uri was not supplied
103 invalid_request code is bad or expired
104 invalid_grant redirect_uri does not match the previous grant
105 invalid_grant this grant was not issued to you!
106 invalid_request refresh_token was not supplied
107 invalid_request refresh disallowed for app
108 invalid_grant bad or expired refresh token
109 invalid_request loginid was not supplied
115 invalid_request unauthenticated client will not be issued token!
117 invalid_request nonce is mandatory for this response_type
118 invalid_request display is invalid
119 invalid_request prompt is invalid
119 invalid_request prompt must be set to consent for offline_access

GET Users Bulk API

This API has been deprecated for the US and EMEA data centers.

Deprecation Date: 6/30/2021

Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.

Learn more in the API Lifecycle & Deprecation Policy.

Obtain Company Token

Company is a top-level principal within SAP Concur and you would be able to obtain an access token and a refresh token on a company's behalf just like you would be able to with a user. Only one authorization flow is currently available for obtaining tokens for a company, which is the Password grant.

For more information and instructions for obtaining a Company Token, please review the Company Level Authentication

Calling Users Bulk API

This endpoint will retrieve a list of users that belong to a company and return basic company information together with the list of users.

Request

URI

Template
GET  /users/

Parameters

Name Type Format Description
total string - The total number of users within the company.
offset string - The offset to begin returning the list of users.
limit string - The number of user records to return in that call. Maximum: 1000
<name_of_filter> string - Filters results based on the desired field. Supported values: isactive, loginid, lastname, employeeid, primaryemail, countrycode, id

Example

Request


GET /users HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: us.api.concursolutions.com

Sample Curl:
curl -v -X GET -H "Authorization: Bearer $token" \
-H "Accept: application/json" \
'https://us.api.concursolutions.com/users/?offset=0&limit=100&isactive=true'

Response

200 OK
{
  "total": 2,
  "offset": 0,
  "limit": 100,
  "company": {
    "name": "Company Name LLC",
    "address": "601 108th ave NE",
    "city": "Bellevue",
    "state": "WA",
    "zip": "98004",
    "country": "US"
  },
  "Items": [
    {
      "Active": true,
      "CountryCode": "US",
      "CellPhoneNumber": "5551234567",
      "PrimaryEmail": "johndoe@gmail.com",
      "EmployeeID": "johndoe@gmail.com",
      "ID": "99BFFFC3-C0BE-44FF-A441-AE1FFFFFF75B8",
      "Emails": ["PrimaryEmail", "VerifiedEmail", "email2", "email3", "email4", "email5"],
      "OrganizationUnit": null,
      "MiddleName": "",
      "LastName": "Doe",
      "FirstName": "John",
      "LoginID": "johndoe@gmail.com"
    },
    {
      "Active": true,
      "CountryCode": "US",
      "CellPhoneNumber": null,
      "PrimaryEmail": "janedoe@gmail.com",
      "EmployeeID": "janedoe@gmail.com",
      "ID": "55FFF504-C7B8-49FF-9E15-6248FFFFFCDB",
      "Emails": ["PrimaryEmail", "VerifiedEmail", "email2", "email3", "email4", "email5"],
      "OrganizationUnit": null,
      "MiddleName": "",
      "LastName": "Doe",
      "FirstName": "Jane",
      "LoginID": "janedoe@gmail.com"
    }
  ]
}

Schema

Property Name Type Format Description
Items array User Required Contains the Client, Users, Locations, Source Partner and Transaction.
NextPage string - The URI of the next page of results, if any.

User

Property Name Type Format Description
Active boolean - Indicates whether the user is currently active or not.
CellPhoneNumber string - The cell phone number of the user.
EmployeeID string - The employee ID of the user.
FirstName string - The first name of the user.
ID string - The unique identifier of the resource.
LastName string - The last name of the user.
LoginID string - The login ID of the user.
MiddleName string - The middle name of the user.
OrginzationUnit string - The organization unit of the user.
PrimaryEmail string - The primary email of the user.
URI string - The URI to the resource.

OAuth2 - Getting Started

The SAP Concur new Oauth2 framework is a very simple way to implement a Unified Token Authentication mechanism within your application. Here is a four step guide to helping you get up to speed and making calls to a SAP Concur API.

Note: The Pre-2017 Authorization (Deprecated) documentation can be found here

1. Obtain Your Application clientID and clientSecret

Before you can obtain an accessToken, you need to register an application with SAP Concur. You can do this by contacting your Partner Enablement Manager or Partner Account Manager. Once you have registered an application, you will receive a clientId, clientSecret and geolocation. The clientId is a unique UUID4 identifier for your application, and the clientSecret is your application's password. You will be using this credential to obtain tokens either for the application itself, or on behalf of a user. The geolocation is your default base URI for initiating all new connections.

2. Obtaining an Access Token

In order for an application to call a SAP Concur API, you need to obtain an accessToken on behalf of either a User, Company or Application. There are multiple ways of obtaining an accessToken through the various grants (Password, Authorization, Client Credentials, One-time Password) .

This section provides a quick start guide for generating an access token. If you are developing an application to be certified for the App Center or as a TripLink supplier, please refer to the certification documentation for the grant types your application must support.

For simplicity, we will use the Password grant flow as an example. The Password grant flow is used when you need to authenticate a user, using its username and password. This is typically reserved from SAP Concur applications (i.e. where the user's credentials will be captured and stored) but is used here for demonstration purposes.

When making the call, you will use your app's geolocation as the base URI followed by the endpoint. For example, if your geolocation is https://us.api.concursolutions.com, you will call https://us.api.concursolutions.com/oauth2/v0/token.

The first time you request for an accessToken a refreshToken is also returned. There are certain conditions where a refreshToken is not returned. This is used to get a new accessToken when one has expired. (see below for more info)

Example shell script using cURL to obtain an accessToken:

oauth2_base=https://us.api.concursolutions.com/oauth2
username=<concur_username> eg. john.doe@gmail.com
password=<password> eg. password1
client_id=<clientId> eg. e01f725d-b4ce-4ce3-a664-b670cb5876cb0
client_secret=<clientSecret> eg. 35c3bd92-fcb8-405e-a886-47ff3fba5664
curl -X POST -H 'concur-correlationid: nameofapp' "$oauth2_base/v0/token" --data "username=$username&password=$password&grant_type=password&client_secret=$client_secret&client_id=$client_id"

Full docs: https://developer.concur.com/api-reference/authentication/apidoc.html#password_grant

Store the token and geolocation.

3. Calling an API with the Access Token

Once you have the accessToken, you need to supply this in an Authorization header in the form of Authorization: Bearer <accessToken> when making a HTTPS call. The accessToken is a large string that looks something like this:

eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IjE0NTU2MTQzNDYifQ.eyJhdWQiOiIqIiwic3ViIjoiaHR0cDovL21zcGNzcHJzcnFhLmNvbmN1ci5jb25jdXJ0ZWNoLm9yZzozMDAzL3Byb2ZpbGUtc2VydmljZS92MS91c2Vycy83NjAwOUFEMy1GNzdCLTREOTgtQTIxQS01NTNDOUM5MTc5RjAiLCJpc3MiOiJodHRwczovL2NvbmN1ci5jb20iLCJleHAiOjE0NzM4OTUxMjksImxlZ2FjeV9hcHBsaWNhdGlvbl9pZCI6MTUwMDA2MzY1OSwidXNlclVSSSI6Imh0dHA6Ly9tc3Bjc3Byc3JxYS5jb25jdXIuY29uY3VydGVjaC5vcmc6MzAwMy9wcm9maWxlLXNlcnZpY2UvdjEvdXNlcnMvNzYwMDlBRDMtRjc3Qi00RDk4LUEyMUEtNTUzQzlDOTE3OUYwIiwidXNlcnV1aWQiOiI3NjAwOUFEMy1GNzdCLTREOTgtQTIxQS01NTNDOUM5MTc5RjAiLCJuYmYiOjE0NzM4OTE1MjksImh0dHBzOi8vYXBpLmNvbmN1cnNvbHV0aW9ucy5jb20vYXBwIjoiaHR0cHM6Ly9hcGkuY29uY3Vyc29sdXRpb25zLmNvbS9hcHAtbWdtdC92MC9hcHBzL2UwMTBlMjVkLWI0Y2UtNGNlMy1hN2U0LWI2NzBjYjFhZGNiMCIsImh0dHBzOi8vYXBpLmNvbmN1cnNvbHV0aW9ucy5jb20vc2NvcGVzIjpbIkNDQVJEIiwiQ09NUEQiLCJVU0VSIiwidXNlcl9yZWFkIiwiRU1FUkciLCJKT0JMT0ciLCJFUkVDUFQiLCJJVElORVIiLCJGSVNWQyIsIkxJU1QiLCJQQVNTViIsIkNPTkZJRyIsIkZPUCIsIkdIT1NUIiwiQ09OUkVRIiwiVFJJUElUIiwiQ09NUEFOWSIsInByb2ZpbGUiLCJFVlMiLCJlbWFpbCIsIlRSVlBUUyIsIkFUVEVORCIsIklOVlBPIiwiTk9USUYiLCJUUlZSRVEiLCJTVVBTVkMiLCJFWFBSUFQiLCJhZGRyZXNzIiwiRVhUUkNUIiwiUEFZQkFUIiwid3Jvbmdfc2NvcGUiLCJJTlZQTVQiLCJJTUFHRSIsIlRBWElOViIsIlJDVElNRyIsIlVOVVRYIiwiVFdTIiwiVE1DU1AiLCJCQU5LIiwiSU5WVkVOIiwib3BlbmlkIiwiTVRORyIsIklOU0dIVCIsIlRSVlBSRiIsIklOVlRWIiwiTUVESUMiLCJUU0FJIl0sImlhdCI6MTQ3Mzg5MTUyOX0.QHY4Mc5A3J981-HDv7KUdgS4tUI-qnmQAxwe9J6DHxuMmYSoGEYZ0dsnLnqc2lO2iVJK6Pg3EBZTArq8_vzV2FK7tA4-IT1eCEHo1e-RWZyWLnR7P56SvZozXpY73daovSH7572HrUm21FXcyLmdaLZyo2LfFcChaghbSCjm1Jg1duH-pLPUW4d89-_pdakmyxfV3GCm2N_XQXoRhNYAAiZcG8UfxEn3TpMHJ96F2n6keJanT_Sn2Sek_sH2EmeeCpg5-jDe0fvLvr1-gY5t0ifq8QBKWHSUUIrGbQvseD6CGzfyiFUqVypN2lukfWACR-26otN50c0OzY6kgY06RA

When you receive the accessToken, store it with the token's geolocation. That geolocation will be the base URI for all subsequent calls.

Armed with the accessToken you can start making calls to an SAP Concur API. Here's an example to retrieve profile information for a User in the Production environment using cURL (utilize the appropriate base URI geolocation for the token). Base URIs Reference:

curl -k -v -H "Accept: application/json" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IjE0NTU2MTQzNDYifQ.eyJhdWQiOiIqIiwic3ViIjoiaHR0cDovL21zcGNzcHJzcnFhLmNvbmN1ci5jb25jdXJ0ZWNoLm9yZzozMDAzL3Byb2ZpbGUtc2VydmljZS92MS91c2Vycy83NjAwOUFEMy1GNzdCLTREOTgtQTIxQS01NTNDOUM5MTc5RjAiLCJpc3MiOiJodHRwczovL2NvbmN1ci5jb20iLCJleHAiOjE0NzM4OTUxMjksImxlZ2FjeV9hcHBsaWNhdGlvbl9pZCI6MTUwMDA2MzY1OSwidXNlclVSSSI6Imh0dHA6Ly9tc3Bjc3Byc3JxYS5jb25jdXIuY29uY3VydGVjaC5vcmc6MzAwMy9wcm9maWxlLXNlcnZpY2UvdjEvdXNlcnMvNzYwMDlBRDMtRjc3Qi00RDk4LUEyMUEtNTUzQzlDOTE3OUYwIiwidXNlcnV1aWQiOiI3NjAwOUFEMy1GNzdCLTREOTgtQTIxQS01NTNDOUM5MTc5RjAiLCJuYmYiOjE0NzM4OTE1MjksImh0dHBzOi8vYXBpLmNvbmN1cnNvbHV0aW9ucy5jb20vYXBwIjoiaHR0cHM6Ly9hcGkuY29uY3Vyc29sdXRpb25zLmNvbS9hcHAtbWdtdC92MC9hcHBzL2UwMTBlMjVkLWI0Y2UtNGNlMy1hN2U0LWI2NzBjYjFhZGNiMCIsImh0dHBzOi8vYXBpLmNvbmN1cnNvbHV0aW9ucy5jb20vc2NvcGVzIjpbIkNDQVJEIiwiQ09NUEQiLCJVU0VSIiwidXNlcl9yZWFkIiwiRU1FUkciLCJKT0JMT0ciLCJFUkVDUFQiLCJJVElORVIiLCJGSVNWQyIsIkxJU1QiLCJQQVNTViIsIkNPTkZJRyIsIkZPUCIsIkdIT1NUIiwiQ09OUkVRIiwiVFJJUElUIiwiQ09NUEFOWSIsInByb2ZpbGUiLCJFVlMiLCJlbWFpbCIsIlRSVlBUUyIsIkFUVEVORCIsIklOVlBPIiwiTk9USUYiLCJUUlZSRVEiLCJTVVBTVkMiLCJFWFBSUFQiLCJhZGRyZXNzIiwiRVhUUkNUIiwiUEFZQkFUIiwid3Jvbmdfc2NvcGUiLCJJTlZQTVQiLCJJTUFHRSIsIlRBWElOViIsIlJDVElNRyIsIlVOVVRYIiwiVFdTIiwiVE1DU1AiLCJCQU5LIiwiSU5WVkVOIiwib3BlbmlkIiwiTVRORyIsIklOU0dIVCIsIlRSVlBSRiIsIklOVlRWIiwiTUVESUMiLCJUU0FJIl0sImlhdCI6MTQ3Mzg5MTUyOX0.QHY4Mc5A3J981-HDv7KUdgS4tUI-qnmQAxwe9J6DHxuMmYSoGEYZ0dsnLnqc2lO2iVJK6Pg3EBZTArq8_vzV2FK7tA4-IT1eCEHo1e-RWZyWLnR7P56SvZozXpY73daovSH7572HrUm21FXcyLmdaLZyo2LfFcChaghbSCjm1Jg1duH-pLPUW4d89-_pdakmyxfV3GCm2N_XQXoRhNYAAiZcG8UfxEn3TpMHJ96F2n6keJanT_Sn2Sek_sH2EmeeCpg5-jDe0fvLvr1-gY5t0ifq8QBKWHSUUIrGbQvseD6CGzfyiFUqVypN2lukfWACR-26otN50c0OzY6kgY06RA" \
https://us.api.concursolutions.com/profile/v1/me

and the response will look like:

{
  "addresses": [
    {
      "type": "Home",
      "streetAddress": "",
      "locality": "",
      "region": "",
      "postalCode": "",
      "country": "US"
    },
    {
      "type": "Work",
      "streetAddress": "",
      "locality": "",
      "region": "",
      "postalCode": "",
      "country": "US"
    }
  ],
  "travelIds": {
    "userId": 85663431,
    "companyId": "63E447F6-A6A7-4B70-A951-10F45d693B43",
    "companyInternalId": 222458,
    "setId": 91157361,
    "ruleClassId": 394103,
    "travelConfigId": 0
  },
  "meta": {
    "created": "2016-06-08T00:00:00.000",
    "lastModified": "2016-08-22T14:32:00.000",
    "resourceType": "EnterpriseUser"
  },
  "displayName": "Brown",
  "name": {
    "formatted": "Brown, Terry ",
    "familyName": "Brown",
    "givenName": "Terry",
    "middleName": "",
    "honorificPrefix": "",
    "honorificSuffix": ""
  },
  "phoneNumbers": [
    {
      "type": "Home",
      "value": "tel:+1-4251231244",
      "primary": false,
      "notifications": false,
      "countryCode": "US",
      "countryISDCode": "1"
    },
    {
      "type": "Work",
      "value": "tel:+1-4251231234;ext=",
      "primary": false,
      "notifications": false,
      "countryCode": "US",
      "countryISDCode": "1"
    }
  ],
  "com:concur:Employee:1.0": {
    "employeeId": "brown@brown-sandbox.com",
    "jobTitle": "",
    "managerId": null,
    "orgUnitId": null
  },
  "dateOfBirth": null,
  "schemas": [
    "com:concur:User:1.0",
    "com:concur:Employee:1.0"
  ],
  "active": true,
  "id": "e01f725d-b4ce-4ce3-a664-b670cb5876cb0",
  "com:concur:TravelPreferences:1.0": {
    "air": {
      "seat": {
        "interrowPosition": null,
        "sectionPosition": null
      },
      "meal": "DontCare",
      "homeAirport": null
    },
    "rail": {
      "space": "DontCare",
      "meal": "DontCare",
      "bedCategory": "DontCare",
      "fareSpaceComfort": "DontCare",
      "deck": "DontCare",
      "coach": "DontCare",
      "bed": "DontCare",
      "berth": "DontCare",
      "noiseComfort": "DontCare",
      "contingency": "DontCare",
      "seat": "DontCare"
    },
    "car": {
      "smoking": "DontCare",
      "carType": "DontCare",
      "transmission": "DontCare",
      "gpsEnabled": false,
      "skirack": false
    },
    "hotel": {
      "earlyCheckin": false,
      "remark": null,
      "pool": false,
      "roomService": false,
      "foamPillows": false,
      "accessForBlind": false,
      "accessForWheelchair": false,
      "gym": false,
      "roomType": "DontCare",
      "restaurant": false,
      "rollawayBed": false,
      "smoking": "DontCare",
      "crib": false
    }
  },
  "gender": null,
  "emails": [
    {
      "value": "brown@brown-sandbox.com",
      "type": "Business",
      "notifications": true
    }
  ],
  "userType": "Enterprise"
}

Full docs: https://developer.concur.com/api-reference/user/

4. Access Token Expiry and Obtaining a Fresh One

Access Tokens have a default One hour lifetime. In order to obtain a fresh accessToken you need to call the auth endpoint using the Refresh Grant. This will return a brand new accessToken and a refreshToken. Refresh Tokens have a default 6 month lifetime. Clients will typically store the refreshToken together with the other user metadata like login information and unique identifiers.

Utilizing the geolocation for the token, here's an example of a cURL call to obtain a new accessToken

curl -X POST 'https://us.api.concursolutions.com/oauth2/v0/token' --data "client_id=$client_id&client_secret=$client_secret&grant_type=refresh_token&refresh_token=<old refresh token>"

Full docs: https://developer.concur.com/api-reference/authentication/apidoc.html#refresh_token

Now that you've made your first call, read up more about the SAP Concur APIs and how they can enhance your application or solve your business needs.

ref: https://developer.concur.com/api-reference/index.html

Migrating old tokens to new Oauth2 Bearer Tokens

Existing applications that use the Pre-2017 Authorization (Deprecated) framework need to move to support the new Oauth2 Bearer Tokens. Applications will need to migrate their existing users who already have connected to it to obtain new Oauth2 tokens without requiring users to reauthorize. This can be done by exchanging an old access token for a new refresh token.

Base URIs

When making API calls, the appropriate base URI for the user's geolocation should be used. See the Base URIs page for the full list.

Exchanging a Token

In order to support new Oauth2, applications need to exchange old access token for new accessToken and refreshToken pair. Once obtained, applications should store these refreshTokens as part of users authorization data.

The new Oauth2 accessToken has a one hour lifetime. Once expired, applications would need to call Oauth2's /v0/token endpoint using a refresh_grant, passing in the user's refreshtoken to obtain a fresh accessToken.

This is significantly different from how the deprecated /net2/Oauth2's method of handling access tokens. Partner's would have to store the new Oauth2 refreshToken instead of the old access token. Before making a call to any of the new v4 APIs, it is advisable to request for a new accessToken before making the API call.

Step 1: Obtain Application Token Clients can exchange OLD tokens for NEW Oauth2 tokens by calling the exchangeRefreshToken/me endpoint. In order to call this endpoint, you would first need to obtain an Application Token by calling the /v0/token endpoint with the client_credentials grant.

The endpoint also supports a parameter called "returnType=companyToken" This parameter allows a partner who already has what is known as a "WSAdmin" token for a client, to exchange that token for a Company level refresh token.

Step 2: Call exchangeRefreshToken

POST /appmgmt/v0/legacyApps/{OLDConsumerKey}/exchangeRefreshToken/me

If you are exchanging a WSAdmin token for a new Company level refresh token:

POST /appmgmt/v0/legacyApps/{OLDConsumerKey}/exchangeRefreshToken/me?returnType=companyToken

Request Header

Name Type Format Description
Authorization string Bearer <accessToken> Required The NEW client_credentials accessToken.

Request Body

Name Type Format Description
token string Required The OLD refreshToken
secret string Required The NEW application client_secret

Sample Curl:

curl -H 'Authorization: Bearer <accessToken>' -d '{"token": "1_oaCof444CaiNXg1FFG$Perr19qIo", "secret": "12345"}' -X POST https://us.api.concursolutions.com/appmgmt/v0/legacyApps/Bwu0mvTHtKYAnBb3Pgu9AW/exchangeRefreshToken/me

successful call, responds with

200 OK
{
  "token": "8c844478-745c-4c45-adf7-1e2777a50dbf",
  "created": 1479407196809,
  "expired": 1494959196809,
  "scopes": [
    "EXPRPT",
    "LIST",
    "BANK",
    "CCARD"
  ],
  "context": "{\"userid\":\"7934467f-dcd1-4631-ba34-3ebd28343e8f\",\"cid\":\"3a55c75e-ac1e-4515-845c-0a4978452828\",\"ptype\":\"user\",\"userURI\":\"https://us.api.concursolutions.com/profile-service/v1/users/7934467f-dcd1-4631-ba34-3ebd28343e8f\",\"scope\":\"EXPRPT LIST BANK CCARD\"}"
}

Sample Curl for WSAdmin token exchange for Company level refreh token:

curl -H 'Authorization: Bearer <accessToken>' -d '{"token": "1_oaCof444CaiNXg1FFG$Perr19qIo", "secret": "12345"}' -X POST https://us.api.concursolutions.com/appmgmt/v0/legacyApps/Bwu0mvTHtKYAnBb3Pgu9AW/exchangeRefreshToken/me?returnType=companyToken

successful call, responds with

200 OK
{
  "token": "8c844478-745c-4c45-adf7-1e2777a50dbf",
  "created": 1479407196809,
  "expired": 1494959196809,
  "scopes": [
    "EXPRPT",
    "LIST",
    "BANK",
    "CCARD"
  ],
  "context": "{\"userid\":\"7934467f-dcd1-4631-ba34-3ebd28343e8f\",\"cid\":\"3a55c75e-ac1e-4515-845c-0a4978452828\",\"ptype\":\"company\",\"userURI\":\"https://us.api.concursolutions.com/profile-service/v1/users/7934467f-dcd1-4631-ba34-3ebd28343e8f\",\"scope\":\"EXPRPT LIST BANK CCARD\"}"
}

Step 3: Obtain New Access Token

Once you have the NEW refreshToken from the response (8c844478-745c-4c45-adf7-1e2777a50dbf) you can then proceed to call /v0/token using the refresh grant to obtain a NEW Oauth2 accessToken.

Sample Curl:

curl -X POST 'https://us.api.concursolutions.com/oauth2/v0/token' -d 'client_id=3a55c75e-ac1e-4515-845c-0a4978452828&client_secret=12345&grant_type=refresh_token&refresh_token=8c844478-745c-4c45-adf7-1e2777a50dbf'

successful call, responds with:

200 OK
{
  "expires_in": 3600,
  "scope": "EXPRPT LIST BANK CCARD",
  "token_type": "Bearer",
  "access_token": "eyJ0...demo...eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IjE0NTU2MTQzNDYifQ.eyJjb25jdXIuc2NvcGVzIjpbIkVYUFJQVCIsIkxJU1QiLCJCQU5LIiwiQ0NBUkQiXSwiYXVkIjoiKiIsImNvbmN1ci5wcm9maWxlIjoiaHR0cHM6Ly91cy1ycWEzLmFwaS5jb25jdXJzb2x1dGlvbnMuY29tL3Byb2ZpbGUvdjEvcHJpY2lwYWxzLzc5NmI0NjdmLWRjZDEtNDYzMS1iYTg1LTNlYmQyOGIzNmU4ZiIsImNvbmN1ci52ZXJzaW9uIjoyLCJjb25jdXIudHlwZSI6InVzZXIiLCJjb25jdXIuYXBwIjoiaHR0cHM6Ly91cy1ycWEzLmFwaS5jb25jdXJzb2x1dGlvbnMuY29tL3Byb2ZpbGUvdjEvYXBwcy9lMDEwZTI1ZC1iNGNlLTRjZTMtYTdlNiLCJzdWIiOiI3OTZiNDY3Zi1kY2QxLTQ2MzEtYmE4NS0zZWJkMjhiMzZlOGYiLCJpc3MiOiJodHRwczovL3VzLXJxYTMuYXBpLmNvbmN1cnNvbHV0aW9ucy5jb20iLCJleHAiOjE0Nzk0MTU4NjksImxlZ2FjeV9hcHBsaWNhdGlvbl9pZCI6MTUwMDA2MzY1OSwidXNlclVSSSI6Imh0dHBzOi8vdXMtcnFhMy5hcGkuY29uY3Vyc29sdXRpb25zLmNvbS9wcm9maWxlLXNlcnZpY2UvdjEvdXNlcnMvNzk2YjQ2N2YtZGNkMS00NjMxLWJhODUtM2ViZDI4YjM2ZThmIiwidXNlcnV1aWQiOiI3OTZiNDY3Zi1kY2QxLTQ2MzEtYmE4NS0zZWJkMjhiMzZlOGYiLCJuYmYiOjE0Nzk0MTIyNjksImh0dHBzOi8vYXBpLmNvbmN1cnNvbHV0aW9ucyiaHR0cHM6Ly91cy1ycWEzLmFwaS5jb25jdXJzb2x1dGlvbnMuY29tL3Byb2ZpbGUvdjEvYXBwcy9lMDEwZTI1ZC1iNGNlLTRjZTMtYTdlNC1iNjcwY2IxYWRjYjAiLCJodHRwczovL2FwaS5jb25jdXJzb2x1dGlvbnMuY29tL3Njb3BlcyI6WyJFWFBSUFQiLCJMSVNUIiwiQkFOSyIsIkNDQVJEIl0sImlhdCI6MTQ3OTQxMjI2OX0.I4EeqKZbpfFonitGBZnLBb20NwMjZNNp5e1d3-BRsepEcJSVCVYIV9HAB2EkkopvoLJsAittiZgD0iDwuh2WVgUt_c4QGzNc_-rXRtCIeKyPQRvxUZNQ7y5RTqEQFNo7hrtXiNZ-yV30zlbijP-12XU5Cu4n2VXgRKxvcCUr5j0RcovUc6O0aOR7VTzj4ZbiDdijOEtmKWGluAYyfIlz8XF2aErAB5Jff2fr9UvgHgtbleYV7eBSesvd9hJEk4S-OAtmFoJwLDECLtLcBKyeHnPEe7LmkLYShcflWG2_tYk4ysPIMG6ne5kRNxJKsDbkMItjpXhujBEGi7YIPWtFWQ",
  "refresh_token": "31456dcd-b46a-4292-b2d3-f97033338487",
  "geolocation": "https://us.api.concursolutions.com"
}

Response Codes

HTTP Status returned by exchangeAccessToken
HTTP Status Description
200 OK - Successful call, response is in body.
400 Bad Request - see list of responses below.
404 Not Found
500 Server Error, error message is in body.
503 Server Timed Out, error message is in body.
exchangeAccessToken Response Codes
CODE Description
OK OK - Successful call, response is in body.
INVALIDSCOPES One or more scopes requested are not a subset of the allowed scopes.
INVALIDAPP Application is invalid
INVALIDTOKEN Bad or expired token
UNAUTHORIZED Invalid credentials
HTTP Status returned by oauth2
HTTP Status Description
200 OK - Successful call, response is in body.
400 Bad Request (error, error_description, code)
401 Unauthorized (error, error_description, code)
403 Forbidden (error, error_description, code)
404 Not Found (error, error_description, code)
500 Server Error, error message is in body.
503 Server Timed Out, error message is in body.

4xx class errors have a JSON response with the following fields

{
  "code": <number>,
  "error": <error>,
  "error_description": <error_description>
}
/token
Code Error Description
5 invalid_grant Incorrect credentials. Please Retry
10 invalid_grant Account is disabled. Please contact support
11 invalid_grant Account is disabled. Please contact support
12 invalid_grant Logon Denied. Please contact support
13 invalid_grant Logon Denied. Please contact support
14 invalid_grant Account Locked. Please contact support
16 invalid_request user lives elsewhere
19 invalid_grant Incorrect credentials. Please Retry
51 invalid_request username was not supplied
52 invalid_request password was not supplied
53 invalid_client company is not enabled for this client
54 invalid_scope requested scope exceeds granted scope
55 invalid_request we don't know this email
56 invalid_request otp was not supplied
57 invalid_request channel_type missing
58 invalid_request channel_handle missing
59 access_denied client disabled
60 invalid_grant these are not the grants you are looking for
61 invalid_client client not found
62 invalid_request client_id was not supplied
63 invalid_request client_secret was not supplied
64 invalid_client Incorrect credentials. Please Retry
65 invalid_request grant_type was not supplied
80 invalid_request invalid channel type
81 invalid_request bad channel handle
83 invalid_request otp not found
84 invalid_request fact verification failed
85 invalid_request otp verification failed
100 invalid_request backend does not know about this username
101 invalid_request code was not supplied
102 invalid_request redirect_uri was not supplied
103 invalid_request code is bad or expired
104 invalid_grant redirect_uri does not match the previous grant
105 invalid_grant this grant was not issued to you!
106 invalid_request refresh_token was not supplied
107 invalid_request refresh disallowed for app
108 invalid_grant bad or expired refresh token
109 invalid_request loginid was not supplied
115 invalid_request unauthenticated client will not be issued token!
117 invalid_request nonce is mandatory for this response_type
118 invalid_request display is invalid
119 invalid_request prompt is invalid
119 invalid_request prompt must be set to consent for offline_access

Oauth2 Migration Best Practices

Old World Authentication

New World Authentication

1. Oauth2

2. Getting Started

3. Token Management

4. Old auth v.s. new auth diagram

old v.s. new

List of Scopes for all SAP Concur APIs

Scope is a parameter as defined in the OAuth 2.0 standards (RFC6749) to enable a client to specify the scope of the access request. The value of the scope parameter is expressed as a list of space-delimited, case-sensitive strings although some implementations of scope uses a comma-delimited format. Scopes limit access for OAuth2 tokens and do not grant any additional permission beyond that which the client already has.

Scopes apply to applications only. Scopes play a crucial part in defining the ultimate access to a resource by a User.

User’s Roles / Permissions + Claims + Application Scopes

Naming Conventions

Concur services follow these standard naming conventions for scopes.

Template: {resource}.{optional subresource}.{action}
Examples: mileage.rate.read
          receipts.read

List of v4 Actions

{actions} are common authorizations across resources.

Action Description Examples
read Read only access (GET) receipts.read, budgetitem.read
write Read AND Write access (GET, POST, UPDATE etc) company.write, travel.receipts.write
writeonly Write only access mileage.journey.writeonly, receipts.writeonly
delete Delete access N/A

List of v4 API Scopes

These are the list of scopes for the v4+ APIs.

Scope Description
budgetitem.read Read access to budget data including fiscal calendar
budgetitem.write Read and write access to budget data including fiscal calendar
company.read Read company profile
company.write Read and Write company profile
creditcardaccount.read Read credit card account data
expense.report.read Read only access to expense reports, expenses and allocations
expense.report.readwrite Read and write access from/to expense reports, expenses and allocations
expense.report.workflowstatus.write Access to approve/reject an expense report
fiscalcalendar.read Access to fiscal calendar
fiscalcalendar.write Read and write access to fiscal calendar
invoice.providerpayment.write Read access to pending payments, and write access to payment status
mileage.journey.read Read-only access to mileage journey resources
mileage.journey.writeonly Write-only access to mileage journey resources
mileage.rate.read Read-only access to rate configuration resources
mileage.rate.writeonly Write-only access to rate configuration resources
mileage.vehicle.read Read-only access to vehicle resources
mileage.vehicle.writeonly Write-only access to vehicle resources
openid Return OPENID token
purchaserequest.write Write only access to purchase requests
purchaserequest.read Read only access purchase requests
quickexpense.writeonly Write quick expense
realtimeingest.location.writeonly Post user location object upon trip completion
receipts.read Read receipts and invoices
receipts.write Read and Write receipts and invoices
receipts.writeonly Write only access for receipts and invoices
travelallowance.itinerary.read Read only access to itinerary data
travelallowance.itinerary.writeonly Write only access to itinerary data
travelallowance.configuration.read Read only access to itinerary configuration data
travelallowance.configuration.writeonly Write only access to itinerary configuration data
travelallowance.itineraryresult.read Read only access to itinerary result data
travel.receipts.read Read requests for travel receipts
travel.receipts.write Read and write travel receipts
travelrequest.write Read and write travel requests
user.read Read user profile
user.write Read and write user profile

List of Connect API scopes

These are the list of scopes for the existing CONNECT APIs (v1.0 - v3.1)

Scope Description
user_read Read user profile for old USER APIs
ATTEND Attendee List - Add, Update, or Inactivate Attendees
CONFIG Expense Configuration - Update Expense Feature Configuration
CONREQ Connection Request - Get or update connection requests to travel reward programs
ERECPT E-Receipts Provider - Post receipts and invoices, get matching facts
EVS External Validation - Validate Fields Using External Systems
EXPRPT Expense Report - Add, Approve, or Update Expense Reports
CCARD Expense Report - Add, Approve, or Update Expense Reports
BANK Expense Report - Add, Approve, or Update Expense Reports
EXTRCT Extract - Request Extract of Available Data
FISVC Financial Integration - Migrate transactions from Concur to external systems
FOP Form of Payment - Access and update user form of payment information
GHOST Form of Payment - Access and update user form of payment information
IMAGE Imaging - Add or Retrieve Report and Line Item Images
INSGHT Insights - Additional services marketable to users
INVPMT Payment Request - Create ,Retrieve and Update for Payment Request
INVPO Purchase Orders - Add or Update Purchase Orders
INVTV Invoice - Tax Validation
INVVEN Search, Add, Update or Delete Vendors
ITINER Itinerary - Add or Update Itineraries or Bookings
JOBLOG Job Log - Log Start, Detail, End and Ping
LIST List Items - Add, Update, or Delete List Items
MTNG Meeting - Attendee Travel Booking
NOTIF Notifications - View and manage notifications
PAYBAT Payment Batch - Close Batches and Request Batch Export Files
RCTIMG Receipts - Add or Update Receipt and OCR Images
SUPSVC Supplier Service - Get Supplier Data
TAXINV Digital Tax Invoice - Get or Validate Digital Tax Invoices
TRVPRF Travel Profile - Access and update user travel profile information
PASSV Travel Profile - Access and update user travel profile information
COMPD Travel Profile - Access and update user travel profile information
EMERG Travel Profile - Access and update user travel profile information
TSAI Travel Profile - Access and update user travel profile information
TMCSP Travel Profile - Access and update user travel profile information
MEDIC Travel Profile - Access and update user travel profile information
UNUTX Travel Profile - Access and update user travel profile information
TRVPTS Travel Points - Access User Balances and Post Travel Points Transactions
TRVREQ Travel Request - Add, Update or Delete Travel Requests
TWS Travel Approval - Approve or Reject Travel Itineraries
USER Users- Add or Update User Accounts
COMPANY Companies - Add or Update Company profile

Sign in with Concur

Important: This API is currently in pre-release status and is only available to approved early access participants. The API is under development and might change before being generally released. To become an early access participant, contact your SAP Concur Representative.

Introduction

Streamline user onboarding with Sign in with Concur – a new feature that allows new users to log on to a partner application using their Concur credentials. Similar to the single sign-on feature provided by Facebook and other social applications, Sign in with Concur reduces the time and effort involved in setting up an account with our partner apps.

Benefits

For partners

For users

Use Cases

Sign in with Concur solves access and support issues for all of our various types of partner integrations:

Consumer applications

Business travelers use in-policy providers but may not have an existing loyalty account. Gain access to the network of business travelers and expense users of Concur by simplifying their first purchase.

Front office applications

Travel and Expense Policy administrators reduce the company's cost via volume purchasing through your application or service; reduce your integration and support overhead as well by removing the need to manage individual user accounts associate with those customers.

Back office applications

How it Works

Select Sign in with Concur from the site login menu

login screen sample

Pick Authentication Option

Single-sign on users can utilize the "Send a link to my email" option.

sign in

If the user selects "One-time Link":

Enter Email address

sign in email option

Confirmation page

email confirmation

Email example

email sample

If the user selects "Enter Concur Credentials":

sign in username and password option

Complete!

For both authentication flows, once authorized, the account is provisioned and user is logged in

sign in complete

Getting Started

1. Obtain your Application clientID and clientSecret

Before you can integrate Sign in with Concur into your application, you need to register your application with Concur. You can do this by contacting your Partner Enablement Manager or Partner Account Manager. Once you have registered an application, you will receive a clientId and clientSecret. The clientId is a unique UUID4 identifier for your application, and the clientSecret is your application password. You will be using this credential to obtain tokens either for the application itself, or on behalf of a user.

2. Add the button to your application

The first script adds the Concur style library to your page and the second applies the style to your button.

<script
  data-client-id=[yourClientID]
  data-redirect-uri=[yourRedirectURI]
  data-oauth-uri="https://www-us.api.concursolutions.com"
  src="https://static.concursolutions.com/nui/oauth/0.0.1/concur-signin.js">
</script>

<div style="float:right">
  <div id="concur-signin"></div>
</div>

Clicking this button renders the Sign in with Concur screen which presents two options to the user for signing in: 1) using Concur credentials OR 2) using a link sent via email.

Option 2 is designed for users who do not want to use passwords or those that do not have passwords such as Single Sign On (SSO) users.

sign in email option

3. Handle Authorization Completion

When users choose the email option, an email will be sent to the user that contains the redirect_uri chosen by the partner in Step 1. If the user selects the username and password option, after accepting the scopes, the user is also sent to the redirect_uri provided.

There will also be a temporary one-time use code which is appended to this redirect_uri. For example, if our redirect URI is https://www.hipmunk.com/auth/concur/callback, the code will be returned as:

https://www.hipmunk.com/auth/concur/callback?cc=<token>

The call to this redirect_uri will contain a temporary code cc which should be used to obtain an official oauth2 accesstoken and refreshtoken.

The response for a successful call will look like this:

**HTTP/** 1.1200 **OK**

;Content-Type: application/json

Date: date-requested

Content-Length: 3397

Connection: Close

{

  "expires_in":"3600",

  "scope":"app-scope",

  "token_type":"Bearer",

  "access_token":"new-access_token",

  "refresh_token":"new-refresh_token",

  "refresh_expiry":"refresh_token_expiry",

  "geolocation":"https://us.api.concursolutions.com"

}

4. Retrieve User Profile information

Once the partner completes the oauth2 flow, they receive an access_token and refresh_token. Using the access_token and within the hour lifetime of the token, the partner has the ability to call SAP Concur APIs. Your application may call the Profile API to obtain user information in order to provision an account in the partner's application.

TripLink Suppliers see the appendix for more details.

Here's an example to retrieve profile information for a User in the Production environment using cURL ( Base URIs for other Environments):

curl -k -v -H "Accept: application/json"\

-H "Authorization: Bearer …ypN2lukfWACR-26otN50c0OzY6kgY06RA"\

https://us.api.concursolutions.com/profile/v1/me

The response from the Profile service will be a compact version of the User profile. The schema can be found here.

5. Create user's account and log user into partner application immediately for a seamless user experience.

Once the user is logged in, your application must determine whether an existing account exists. Your application can do so by pulling user information from the application and SAP Concur profile.

Existing Accounts

For users connected to SAP Concur through the Concur App Center or otherwise, your application can match the SAP Concur unique user ID.

New SAP Concur Accounts

For users with existing, non-SAP Concur accounts , the unique user information in your application can be matched with information in SAP Concur (e.g. email address).

If the user does not have an existing account , your application must provision a user account. In this case, the partner maintains the user's profile over time. This is beneficial as it allows the app to post data for the user following the initial session. For example, it allows users make changes to a reservation and receive updates within SAP Concur and/or receive receipts for services charged after delivery such as hotel stays.

In all cases, the user's token, geolocation and user UUID should be stored. As applications vary in the information required to create a new user record and utilize the service, your application should leverage data from the user profile endpoint where possible.

Account Maintenance

Once the account is provisioned or matched, the application must:

Error Handling

In all cases, the error description provided by Concur should be displayed to the user.

The following covers special cases that require additional handling.

Authorization Declined

In the case the user leaves the sign in process or sign in is unsuccessful, the user will be redirected to the following:

Your_Redirect_Uri?

 error_code=user_denied

 &error_description=The+user+denied+your+request.

Apps should then provide the user with alternative connection methods:

Application is disabled

Customers have the option to disable applications for their users. In these cases, the user will be redirected to the following:

Your_Redirect_Uri?

 error_code=

 &error_description=

In this case, the user will not be able to access your application using Sign in with Concur. The error description should be displayed to the user and the user given alternate sign in methods (e.g. create an account).

Advanced

This section covers guidelines for specific Sign in with Concur implementations.

Enterprise Applications

Company-wide integrations are unique in that your application will interact with SAP Concur both on a batch level (for example, GET or POST for multiple employees) but also allow individuals to sign in to the service without creating a new account.

When an application supports enterprise integrations, the user's account should be associated with the company's information (company UUID) so that the company token can be used to process batch transactions.

In addition, the administrator will need to identify the users which should have access to your application. Given that, the administrator must first add users to your service. An example of the set up and sign in process are documented below.

Sign in with Concur Set Up

The below diagram illustrates the initial set up process. To set up the connection, the administrator must identify the users of your service.

Note that, in addition to identifying users of the service, your application may also require that roles/permissions be assigned to individual users to determine access to various features and functionality of your service. Role and permissions assignment are not depicted in the diagram below as the requirements may differ for each client application.

Once added to the service, users must then verify their identity before first sign in. This process uses the One-Time Password Grant to first validate the user is the owner of the email address used to uniquely identify that individual. Once validated, the user may sign in with username and password going forward.

set_up_diagram

Signing in to the Client Application

When a user first navigates to your application, you may offer multiple sign in options, including Sign in with Concur. Once signed in, your application must validate that users have completed the one-time verification.

If the user has not completed the one-time verification when visiting your site, the One-Time Password Grant should be initiated on the user's behalf.

The below illustrates the process for users signing in to your service.

sign_in_diagram

Depending on the products the customer has enabled, integrations and features available with Sign in with Concur vary. The following defines the scopes that are applicable product combinations. Your application must support each of the below potential scope configurations:

* Special Note: For TripLink Suppliers that support the Travel Receipts API, this API does not support Expense only users. It is recommended that e-receipts be posted for these or all users via the Receipts API.

To determine which permissions the user has access to, each time a user signs in *, your application should:

  1. Call the User Profile API to get the user's permissions.

A user can have one or more permissions that will dictate the scopes applicable to that user.

  curl -k -v -H "Accept: application/json"\

  -H "Authorization: Bearer …ypN2lukfWACR-26otN50c0OzY6kgY06RA"\

  https://us.api.concursolutions.com/api/user/v1.0/user

The detailed response can be found here: /api-reference/user/ (snippet below).

| Name | Type | Format | Description | | --- | --- | --- | --- | | ExpenseUser | string | | Whether the user has access to Expense. Format: Y/N. | | TripUser | string | | Whether the user has access to Travel. Format: Y/N. |

The response will indicate whether the is an Expense or Travel user.

If an expense user only , only the e-receipts scope is applicable and the user will not be eligible for other travel discounts or automated itinerary creation in Concur.

If a travel user, use the token to call the Travel Profile API .

Within this response, is the "HasOpenBooking" parameter; if "true" the user is eligible for TripLink.

If the user has travel only, they will not receive e-receipts.

  1. Store the user permissions information. (optional)

The user's permissions can then be used to determine which scopes and APIs are applicable for updates to an existing booking and/or e-receipts.

Supported Languages

The following language codes are supported in by Sign in with Concur.

Code Name
en English (US)

BUDGET

Budget v4 - Getting Started

Overview

The Budget service exposes budget and fiscal year data. Partners and clients may use the service endpoints to read and alter fiscal year, budget, budget adjustment, and budget matching configuration. Summary and detailed balance amounts are also available to read, but may not be altered via the API.

The sequence to configure budgets is to first setup the fiscal year and then the budget categories (if applicable) before creating budget items. Budget items may use budget tracking fields as filters. The budget tracking field can only be configured in the application UI. Also budget owner, approver, and budget viewer permissions have to be assigned to users prior to configuring budgets.

Process Flow

A process flow diagram of getting started with Budget APIs

Products and Editions

Scope Usage

This API requires one or more of the following scopes:

Name Description Endpoint
budgetitem.read Grants read access to the budget resources. GET Budget Category, GET Budget Item, GET Budget Tracking Fields, GET Fiscal Year, GET Valid Expense Types
budgetitem.write Grants read and write access to the budget resources. GET Budget Category, GET Budget Item, GET Budget Tracking Fields, GET Fiscal Year, GET Valid Expense Types, POST Budget Adjustment, POST Budget Category, POST Budget Item, POST Fiscal Year, DELETE Budget Category, DELETE Budget Item, DELETE Fiscal Year
fiscalcalendar.read Grants read access to the fiscal calendar. GET All Fiscal Years, GET a Fiscal Year
fiscalcalendar.write Grants read and write access to the fiscal calendar. GET All Fiscal Years, GET a Fiscal Year, POST a Fiscal Year, DELETE a Fiscal Year

Dependencies

SAP Concur clients must purchase Budget in order to use this API.

Access Token Usage

This API supports both company level and user level access tokens. The user needs to have the Budget Administrator role in order to access the API.

Budget v4 - Budget Adjustments

This resource is used to add budget adjustments. Each budget item detail may have one or more budget adjustments and adjustments can be made to manually add or subtract the budget, spent or pending balances.

Create a Budget Adjustment

Create one or more budget adjustments.

Scopes

budgetitem.write - Refer to Scope Usage for full details.

Request

URI

Template
POST /budget/v4/adjustments

Parameters

Name Type Format Description
useMonthlyRollingUpdate boolean query Required If true, all adjustments for a given month, adjustment type, amount type & description will be rolled up to one adjustment. This is useful for an automated process that makes daily or weekly updates and doesn't want to clutter end-user dashboards.

Headers

Payload

Budget Adjustments

Response

Status Codes

Headers

Payload

Either "Success" or an Error Response

Example

Request

POST https://us.api.concursolutions.com/budget/v4/adjustments?useMonthlyRollingUpdate=false
Authorization: Bearer {token}
Content-Type: application/json
Accept: application/json
[
    {
        "budgetItemName":"API Budget-Oregon",
        "fiscalYearName": "2018",
        "budgetOwnerEmail": "m.jones@example.com",
        "fiscalPeriodName": "2018 - Q3",
        "amount": 100,
        "adjustmentType": "FUND_TRANSFER",
        "amountType": "BUDGET_AMOUNT",
        "description": "Initial July Adjustment",
        "transactionDate": "2018-07-11"
    },
    {
        "budgetItemName":"API Budget-Travel",
        "fiscalYearName": "2018",
        "budgetOwnerEmail": "m.jones@example.com",
        "fiscalPeriodName": "2018 - Q3",
        "amount": 100,
        "adjustmentType": "EXPENSE",
        "amountType": "SPENT_AMOUNT",
        "transactionDate": "2018-07-10"
    }
]

Response

Success Response
HTTP/1.1 200 OK
Cache-Control: no-store
Connection: keep-alive
Content-Length: 9
Content-Type: application/json;charset=utf-8
Date: Fri, 21 Sep 2018 15:24:27 GMT
Expires: Thu, 20 Sep 2018 15:24:27 GMT
Pragma: no-cache
Vary: Origin
concur-correlationid: 86a0d9fe-9e98-43c3-89d8-a2917dd844cb
"Success"
Failure Response
HTTP/1.1 400 Bad Request
Cache-Control: no-store
Connection: close
Content-Length: 242
Content-Type: application/json;charset=utf-8
Date: Fri, 21 Sep 2018 15:29:05 GMT
Expires: Thu, 20 Sep 2018 15:29:05 GMT
Pragma: no-cache
concur-correlationid: 561ce34c-6542-4bae-82a2-aa6ccd8c6b22
{
    "message": {  
        "status" : false,
        "errorMessageList" : [
          {
            "errorType" : "ERROR",
            "errorCode" : "BUDGET.BUDGET_PERIOD_REQUIRED",
            "errorMessage" : "Record 1) Record 1) Budget period is missing"
          }
        ]
    }
}

Schema

Budget Adjustment

Name Type Format Description
budgetItemName string - Required The name of the budget of the adjustment.
fiscalYearName string - Required The name of the budget’s fiscal year. The default name for a fiscal year is the numeric, four-digit year. Example: 2019
fiscalPeriodName string - Required The specific fiscal period when this budget amount will be used. The default name for a fiscal period is: Monthly: <fiscal year name> - <three-letter month abbreviation> (Example: 2019 - Jun). Quarterly: <fiscal year name> - Q<number of quarter> (Example: 2019 - Q2). Yearly: <fiscal year name> (Example: 2019).
budgetOwnerEmail string - Required The user who is responsible for the budget, as configured.
amount decimal - Required The budget currency amount to be adjusted. The amount may be a positive or negative value but it cannot be zero.
adjustmentType string - Required The type of adjustment being made. Only a user reference field. Supported values: BUDGET_BALANCE, FUND_TRANSFER, EXPENSE, PAYMENT_REQUEST, PURCHASE_REQUEST, REQUEST
amountType string - Required The type of the budget’s balance to adjust. Affects which values in the budget are updated. Supported values: BUDGET_AMOUNT, SPENT_AMOUNT, PENDING_AMOUNT
description string - A user-friendly description of the adjustment.
transactionDate date YYYY-MM-DD Required if amount type is either SPENT_AMOUNT or PENDING_AMOUNT The transaction date of adjusted spend. Must be within the fiscal period.

Error Response

Name Type Format Description
status boolean - False if there was an error.
errorMessageList array errorMessage List of all errors detected.

Error Message

Name Type Format Description
errorType string - WARNING or ERROR.
errorCode string - Text code for this error.
errorMessage string - Plain language error message.

Budget v4 - Budget Category

This resource is used to retrieve and update budget categories which are collections of expense types used for budget matching. Each budget item header may have one Budget Category. If it does, only line items with expense types contained in that Budget Category will be accumulated to the budget.

GET All Budget Categories

Retrieve a list of all budget categories.

Scopes

This API call requires one of the following scopes:

Request

URI

Template
GET /budget/v4/budgetCategory

Parameters

N/A

Headers

Response

Status Codes

Headers

Response Headers

Payload

Budget Category

Example

Request

GET https://us.api.concursolutions.com/budget/v4/budgetCategory
Authorization: Bearer {token}
Content-Type: application/json

Response

HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 1292
concur-correlationid: 9d59b6f0-e5bd-47bf-bcad-4c3de9f5c45c
[
    {
      "name":"Marketing and Outreach",
      "description":null,
      "statusType":"OPEN",
      "id":"36047f6c-6cf6-443d-a952-39efb012acdb",
      "expenseTypes":[
        {
          "featureTypeCode":"PURCHASE_REQUEST",
          "expenseTypeCode":"MKTG",
          "id":"f35827a8-7981-4a5b-bfc3-da7ebb4665ff",
          "name":null
        },
        {
          "featureTypeCode":"EXPENSE",
          "expenseTypeCode":"SEMNR",
          "id":"30f16783-e50e-4ab4-b6fb-f66cc75956f2",
          "name":null
        },
        {
          "featureTypeCode":"PURCHASE_REQUEST",
          "expenseTypeCode":"ADVT",
          "id":"64a04928-37b0-49c8-99e8-c346e6d47825",
          "name":null
        }
      ]
    },
    {
      "name":"Airfare",
      "description":null,
      "statusType":"OPEN",
      "id":"459fe79a-9b1e-4ea0-8416-19de0ff14eef",
      "expenseTypes":[
        {
          "featureTypeCode":"EXPENSE",
          "expenseTypeCode":"AIRFR",
          "id":"53300041-3fb9-4a93-8cdf-327fcbe74a0c",
          "name":null
        },
        {
          "featureTypeCode":"REQUEST",
          "expenseTypeCode":"AIRFR",
          "id":"29278c5a-624a-4dd6-a2c1-02dd233d3fbf",
          "name":null
        }
      ]
    }     
]

GET a Budget Category

Retreive the details of a single budget category.

Scopes

This API call requires one of the following scopes:

Request

URI

Template
GET  /budget/v4/budgetCategory/{id}

Parameters

Name Type Format Description
id string uuid The budget category's key field.

Headers

Response

Status Codes

Headers

Response Headers

Payload

Budget Category

Example

Request

GET https://us.api.concursolutions.com/budget/v4/budgetCategory/36047f6c-6cf6-443d-a952-39efb012acdb
Authorization: Bearer {token}
Content-Type: application/json

Response

HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 642
concur-correlationid: f7b1a193-46cc-4784-9c6f-d8e1e47ecaa1
{
  "name":"Marketing and Outreach",
  "description":null,
  "statusType":"OPEN",
  "id":"36047f6c-6cf6-443d-a952-39efb012acdb",
  "expenseTypes":[
    {
      "featureTypeCode":"PURCHASE_REQUEST",
      "expenseTypeCode":"MKTG",
      "id":"f35827a8-7981-4a5b-bfc3-da7ebb4665ff",
      "name":null
    },
    {
      "featureTypeCode":"EXPENSE",
      "expenseTypeCode":"SEMNR",
      "id":"30f16783-e50e-4ab4-b6fb-f66cc75956f2",
      "name":null
    },
    {
      "featureTypeCode":"PURCHASE_REQUEST",
      "expenseTypeCode":"ADVT",
      "id":"64a04928-37b0-49c8-99e8-c346e6d47825",
      "name":null
    }
  ]
}

POST a Budget Category

Save a new budget category or update an existing budget category.

Scopes

budgetitem.write - Refer to Scope Usage for full details.

Request

URI

Template
POST  /budget/v4/budgetCategory

Parameters

N/A

Headers

Payload

Budget Category

Response

Status Codes

Headers

Response Headers

Payload

Budget Category or Error Response

Example

Request

POST https://us.api.concursolutions.com/budget/v4/budgetCategory
Authorization: Bearer {token}
Content-Type: application/json
{
  "name": "Advertising Category",
  "description": "Advertising",
  "expenseTypes": [
    {
      "featureTypeCode": "EXPENSE",
      "expenseTypeCode": "ADVT"
    },
    {
      "featureTypeCode": "PAYMENT_REQUEST",
      "expenseTypeCode": "ADVT"
    }
  ],
  "statusType": "OPEN"
}

Response

Success Response
HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 1270
concur-correlationid: 5c00e59f-d00c-4019-8d3d-47130d8e37b4
{
  "name": "Advertising Category",
  "description": "Advertising",
  "id": "d9fd5191-7016-4f50-a6c8-4770bddc01d8",
  "statusType": "OPEN",
  "expenseTypes": [
    {
      "id": "e1dd44da-25b4-4180-8d89-00f3a8d8cf4e",
      "featureTypeCode": "EXPENSE",
      "expenseTypeCode": "ADVT",
      "name": null
    },
    {
      "id": "67253ac1-77e0-4d61-a478-0d194611b320",
      "featureTypeCode": "PAYMENT_REQUEST",
      "expenseTypeCode": "ADVT",
      "name": null
    }
  ]
}
Failure Response
HTTP/1.1 400 Bad Request
Cache-Control: no-store
Connection: close
Content-Length: 338
Content-Type: application/json;charset=utf-8
Date: Fri, 21 Sep 2018 15:27:05 GMT
Expires: Thu, 20 Sep 2018 15:27:05 GMT
Pragma: no-cache
concur-correlationid: 44adb686-a624-4ee5-b618-e4ea31a95bec
{
  "status" : false,
  "errorMessageList" : [
    {
      "errorType" : "ERROR",
      "errorCode" : "BUDGET.BUDGET_CATEGORY_NAME_REQUIRED",
      "errorMessage" : "Budget category name is required"
    },
    {
      "errorType" : "ERROR",
      "errorCode" : "BUDGET.BUDGET_CATEGORY_NAME_UNIQUE_ERROR",
      "errorMessage" : "Budget category must have a unique name"
    }
  ]
}

DELETE a Budget Category

Delete a budget category. Budget categories that are in use by budget items may not be deleted.

Scopes

budgetitem.write - Refer to Scope Usage for full details.

Request

URI

Template
DELETE  /budget/v4/budgetCategory/{id}

Parameters

Name Type Format Description
id string uuid The budget category's key field.

Headers

Response

Status Codes

Headers

Response Headers

Example

Request

DELETE https://us.api.concursolutions.com/budget/v4/budgetCategory/a5e00b3f-b941-4522-8b0e-07412fb2cc7c
Authorization: Bearer {token}
Content-Type: application/json

Response

HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 0
concur-correlationid: 39216840-2808-4c49-8874-e9862d96fdb6

GET All Valid Expense Types

Retrieve a list of all possible expense types that may be used in a budget category.

Scopes

This API call requires one of the following scopes:

Request

URI

Template
GET  /budget/v4/budgetCategory/expenseTypes

Parameters

N/A

Headers

Response

Status Codes

Headers

Response Headers

Payload

Expense Type

Example

Request

GET https://us.api.concursolutions.com/budget/v4/budgetCategory/expenseTypes
Authorization: Bearer {token}
Accept: application/json

Response

HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 367
concur-correlationid: 7afa7091-bc4e-4408-8248-a67f9e24a023
[
  {
    "featureTypeCode":"EXPENSE",
    "expenseTypeCode":"AIRFR",
    "id":null,
    "name":"Airfare"
  },
  {
    "featureTypeCode":"EXPENSE",
    "expenseTypeCode":"AIRTX",
    "id":null,
    "name":"Airfare Ticket Tax"
  },
  {
    "featureTypeCode":"PAYMENT_REQUEST",
    "expenseTypeCode":"CATER",
    "id":null,
    "name":"Catering"
  }
]

Schema

BudgetCategory

Name Type Format Description
description string - The friendly name for this category.
expenseTypes array expenseType Required The list of expense types that this budget category matches.
name string - Required The admin-facing name for this category.
statusType string - The status of this budget category. Supported values: OPEN, REMOVED
id string - The unique identifier for the budget category.

ExpenseType

Name Type Format Description
featureTypeCode string - Required The type of feature that this expense type applies to: Purchase Request, Payment Request (Invoice), Expense, or Travel Authorization. Supported values: PURCHASE_REQUEST, PAYMENT_REQUEST, EXPENSE, REQUEST
expenseTypeCode string - Required The alphanumeric code that describes an expense type (Example: MEALS, AC_CATER). Any string may be used, but only expense type codes returned by GET /budgetCategory/expenseType will behave properly in the SAP Concur UI.
name string - READ ONLY The name for this expense type if it maps to an expense type set up in SAP Concur.
id string - The budget service's key for this object. If this field is not supplied, the service will use an existing expense type entry if one exists.

Error Response

Name Type Format Description
status boolean - False if there was an error.
errorMessageList array errorMessage List of all errors detected.

Error Message

Name Type Format Description
errorType String - WARNING or ERROR.
errorCode String - Text code for this error.
errorMessage String - Plain language error message.

Response Headers

Budget v4 - Budget Item

This resource is used to retrieve and update information about a budget that spans a single fiscal year. Each budget has multiple details that correspond to fiscal periods - months, quarters, or a single period for a yearly budget.

GET All Budget Items

Retrieve all budget items in groups of up to 50 items. Due to response size and performance considerations, this endpoint does not return budgetItemDetails. Use the GET a Budget Item to retrieve all the details for a single budget.

Scopes

This API call requires one of the following scopes:

Request

URI

Template
GET /budget/v4/budgetItemHeader

Parameters

Name Type Format Description
adminView boolean query If true, returns all budgets for this entity, if false, returns only the budgets owned by the current user. Default: false
offset integer query The start of the page offset. Default: 0

Headers

Response

Status Codes

Headers

Response Headers

Payload

Budget Item Header List

Example

Request

GET https://us.api.concursolutions.com/budget/v4/budgetItemHeader
Authorization: Bearer {token}
Accept: application/json

Response

HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 1270
concur-correlationid: dd6cee88-b725-4c06-9ee9-0ca4ae4f16b2
{
  "totalRows":122,"offset":0,"limit":50,
  "budgetItemHeaders":[
    {
        "name":"Marketing-US-Jean Normandy",
        "isTest":false,
        "budgetItemStatusType":"OPEN",
        "description":"Marketing-US",
        "id":"72eee673-3d81-49c2-966a-b63c7a9302e6",
        "costObjects":[
         {
          "code": "6",
          "fieldDefinitionId": "86eee673-3d81-49c2-966a-b63c7a9302e2",
          "value": "2",
          "listKey": "1334",
          "operator": "EQUAL",
          "displayName": "Country Code"
        }
        ],
        "periodType":"YEARLY",
        "active":true,
        "owned":false,
        "budgetAmounts":{
          "pendingAmount":1178.37697091,
          "unExpensedAmount":2310.73578092,
          "spendAmount":35.78378912,
          "adjustedBudgetAmount": 0,
          "availableAmount":8785.83923997,
          "unExpensedSettings":null,
          "threshold":"UNDER",
          "consumedPercent":12
        },
        "createdDate": "2019-06-26T17:49:53.102Z",
        "budgetItemHeaderId":"72eee673-3d81-49c2-966a-b63c7a9302e6",
        "budgetName":"Marketing-US-Jean Normandy",
        "currencyCode":"EUR",
        "annualBudget":10000.00000000,
        "budgetCategory":{
          "name":"airfare",
          "description":null,
          "statusType":"OPEN",
          "id":"27451c2d-9121-44bd-b4b0-f2119d2071c7"
        },
        "owner":{
          "externalUserCUUID":"8002250890004822936",
          "employeeUuid":"210fe25f-e326-495c-847a-de333173f616",
          "id":"f779261d-77ce-4123-b739-d842ef6f104d",
          "name":"Jean Normandy",
          "email":"jean.normandy@xyz.com",
          "employeeId":"jean.normandy"
         },
        "budgetApprovers":[
          {
            "externalUserCUUID":"8002250890004822936",
            "employeeUuid":"210fe25f-e326-495c-847a-de333173f616",
            "id":"f779261d-77ce-4123-b739-d842ef6f104d",
            "name":"Jean Normandy",
            "email":"jean.normandy@xyz.com",
            "employeeId":"jean.normandy"
          }
        ],
        "budgetManagers":[
          {
            "externalUserCUUID":"1563846384638464842",
            "employeeUuid":"13a13839-68d6-4ee8-90e9-58604278aa8f",
            "id":"e2bae688-e000-464a-8728-e1362c94f172",
            "name":"Walter Gupta",
            "email":"walter.gupta@xyz.com",
            "employeeId":"walter.gupta"
          }
        ],
        "budgetType": "PERSONAL_USE",
        "budgetViewers":[
          {
            "externalUserCUUID":"5005380230004873464",
            "employeeUuid":"eb6082b0-3a9a-4e79-a350-e6e067f34969",
            "id":"7ce7dfe0-6168-4b93-bb35-386bf023acc6",
            "name":"Dan Lee",
            "email":"dan.lee@xyz.com",
            "employeeId":"dan.lee"
          }
        ],
        "dateRange": null,
        "fiscalYear":{
          "name":"2017",
          "displayName":"2017",
          "startDate":"2017-01-01",
          "endDate":"2017-12-31",
          "status":"OPEN",
          "id":"a4f9d57f-14ac-4f03-b5aa-4256e5cff790",
          "lastModified":"2017-03-26 20:53:19",
          "currentYear":false
        }
      },
    {"Additional budget item headers removed for brevity":"Additional budget items headers removed for brevity"}
  ],
  "href":"https://us.api.concursolutions.com/budget/v1.1/budgetItemHeader/?offset=0",
  "next":{
    "href":"http://budget-service-rqa3-budget.us-west-2.nonprod.cnqr.delivery/budget/v1.1/budgetItemHeader/?adminView=true&offset=50"
  },
  "previous":null
}

GET a Budget Item

Retrieve the details of a single budget item.

Scopes

This API call requires one of the following scopes:

Request

URI

Template
GET  /budget/v4/budgetItemHeader/{id}

Parameters

Name Type Format Description
id string uuid The budget item header's key field.

Headers

Response

Status Codes

Headers

Response Headers

Payload

Budget Item Header

Example

Request

GET https://us.api.concursolutions.com/budget/v4/budgetItemHeader/72eee673-3d81-49c2-966a-b63c7a9302e6
Authorization: Bearer {token}

Response

HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 1270
concur-correlationid: 918cfb55-06a1-47da-8ef1-774a45427af9
 {
    "name":"Marketing-US-Jean Normandy",
    "isTest":false,
    "budgetItemStatusType":"OPEN",
    "description":"Marketing-US",
    "id":"72eee673-3d81-49c2-966a-b63c7a9302e6",
    "costObjects":[
     {
          "code": "6",
          "fieldDefinitionId": "86eee673-3d81-49c2-966a-b63c7a9302e2",
          "value": "2",
          "listKey": "1334",
          "operator": "EQUAL",
          "displayName": "Country Code"
        }
    ],
    "periodType":"QUARTERLY",
    "active":true,
    "owned":false,
    "budgetAmounts":{
      "pendingAmount":6870.48165307,
      "unExpensedAmount":102126.89000000,
      "spendAmount":764.86966050,
      "adjustedBudgetAmount": 0,
      "availableAmount":2364.64868643,
      "unExpensedSettings":null,
      "threshold":"UNDER",
      "consumedPercent":76
    },
    "createdDate": "2019-06-26T17:49:53.102Z",
    "currencyCode":"EUR",
    "annualBudget":10000.00000000,
    "budgetCategory":null,
    "owner":{
      "externalUserCUUID":"8002250890004822936",
      "employeeUuid":"210fe25f-e326-495c-847a-de333173f616",
      "id":"f779261d-77ce-4123-b739-d842ef6f104d",
      "name":"Jean Normandy",
      "email":"jean.normandy@xyz.com",
      "employeeId":"jean.normandy"
     },
    "budgetApprovers":[
       {
        "externalUserCUUID":"8002250890004822936",
        "employeeUuid":"210fe25f-e326-495c-847a-de333173f616",
        "id":"f779261d-77ce-4123-b739-d842ef6f104d",
        "name":"Jean Normandy",
        "email":"jean.normandy@xyz.com",
        "employeeId":"jean.normandy"
       }
    ],
    "budgetManagers":[
      {
        "externalUserCUUID":"1563846384638464842",
        "employeeUuid":"13a13839-68d6-4ee8-90e9-58604278aa8f",
        "id":"e2bae688-e000-464a-8728-e1362c94f172",
        "name":"Walter Gupta",
        "email":"walter.gupta@xyz.com",
        "employeeId":"walter.gupta"
      }
    ],
    "budgetType": "PERSONAL_USE",
    "budgetViewers":[
      {
        "externalUserCUUID":"5005380230004873464",
        "employeeUuid":"eb6082b0-3a9a-4e79-a350-e6e067f34969",
        "id":"7ce7dfe0-6168-4b93-bb35-386bf023acc6",
        "name":"Dan Lee",
        "email":"dan.lee@xyz.com",
        "employeeId":"dan.lee"
      }
    ],
    "budgetItemDetails":[
      {
        "budgetItemHeaderId":"72eee673-3d81-49c2-966a-b63c7a9302e6",
        "budgetName":"Marketing-US-Jean Normandy",
        "currencyCode":"USD",
        "amount":2500.00000000,
        "id":"4c165d40-804f-4aaa-b900-a46538537f6a",
        "budgetItemDetailStatusType":"OPEN",
        "budgetAmounts":{
          "pendingAmount":6870.48165307,
          "unExpensedAmount":102126.89000000,
          "spendAmount":764.86966050,
          "adjustedBudgetAmount": 0,
          "availableAmount":-5135.35131357,
          "unExpensedSettings":null,
          "consumedPercent":305,
          "threshold":"OVER"
        },
        "detailDashboardBudgetItemAdjustmentDTOs": [
          {
            "adjustmentType": "BUDGET_BALANCE",
            "amount": 0,
            "amountType": "QUICK_EXPENSE",
            "description": "string",
            "transactionDate": "2019-06-26"
          }
        ],
        "fiscalPeriod":{
          "name":"2017 - Q1",
          "fiscalPeriodStatus":"OPEN",
          "id":"b9659f8a-4e74-4531-9e23-1222ab1507f2",
          "periodType":"QUARTERLY",
          "startDate":"2017-01-01",
          "endDate":"2017-03-31",
          "spendDate":null,
          "fiscalYearId":"bcb41c95-2d53-4a1a-830f-7c6b01fa79da",
          "currentPeriod":false
        },
        "budgetItemBalances":[
          {
            "featureTypeCode":"PURCHASE_REQUEST",
            "featureTypeSubCode":"NONE",
            "workflowState":"SUBMITTED",
            "amount":6870.48165307,
            "id":"11cb732e-cbc4-41cb-82be-162d632d5499"
          },
          {
            "featureTypeCode":"EXPENSE",
            "featureTypeSubCode":"NONE",
            "workflowState":"PAID",
            "amount":764.86966050,
            "id":"0f09cc65-b879-4969-a8a1-9dd52c96486d"
          },
          {
            "featureTypeCode":"EXPENSE",
            "featureTypeSubCode":"ERECEIPTS",
            "workflowState":"UNSUBMITTED",
            "amount":102126.89000000,
            "id":"27c49c8a-c24d-42eb-b089-84268350ae03"
          }
        ]
      },
      {
        "budgetItemHeaderId":"72eee673-3d81-49c2-966a-b63c7a9302e6",
        "budgetName":"Marketing-US-Jean Normandy",
        "currencyCode":"EUR",
        "amount":2500.00000000,
        "id":"0a2dc181-389e-4c85-bb57-e4f1a11ace4e",
        "budgetItemDetailStatusType":"OPEN",
        "budgetAmounts":{
          "pendingAmount":0,
          "unExpensedAmount":0,
          "spendAmount":0,
          "adjustedBudgetAmount": 0,
          "availableAmount":2500.00000000,
          "unExpensedSettings":null,
          "consumedPercent":0,
          "threshold":"UNDER"
        },
        "detailDashboardBudgetItemAdjustmentDTOs": [
          {
            "adjustmentType": "BUDGET_BALANCE",
            "amount": 0,
            "amountType": "QUICK_EXPENSE",
            "description": "string",
            "transactionDate": "2019-06-26"
          }
        ],
        "fiscalPeriod":{
          "name":"2017 - Q2",
          "fiscalPeriodStatus":"OPEN",
          "id":"590d4e22-40be-43cc-ac1b-01b0d0263e19",
          "periodType":"QUARTERLY",
          "startDate":"2017-04-01",
          "endDate":"2017-06-30",
          "spendDate":null,
          "fiscalYearId":"bcb41c95-2d53-4a1a-830f-7c6b01fa79da",
          "currentPeriod":true
        },
        "budgetItemBalances":[]
      },
      {
        "Additional budget item details removed for brevity": "Additional budget item details removed for brevity"
      }
    ],
    "dateRange": null,
    "fiscalYear":{
      "name":"2017",
      "displayName":"2017",
      "startDate":"2017-01-01",
      "endDate":"2017-12-31",
      "status":"OPEN",
      "id":"a4f9d57f-14ac-4f03-b5aa-4256e5cff790",
      "lastModified":"2017-03-26 20:53:19",
      "currentYear":false,
      "monthlyFiscalPeriods":[
        {
          "name":"2017-Special - Jan",
          "fiscalPeriodStatus":"OPEN",
          "periodType":"MONTHLY",
          "startDate":"2017-01-01",
          "endDate":"2017-01-31",
          "id":"1929d1d9-6c99-4635-9272-508364193f8f",
          "spendDate":null,
          "fiscalYearId":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
          "currentPeriod":false
        },
        {
          "name":"2017-Special - Feb",
          "fiscalPeriodStatus":"OPEN",
          "periodType":"MONTHLY",
          "startDate":"2017-02-01",
          "endDate":"2017-02-28",
          "id":"41aa7452-e52a-4fd6-9c8a-5b199edeadaf",
          "spendDate":null,
          "fiscalYearId":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
          "currentPeriod":false
        },
        {
          "name":"2017-Special - Mar",
          "fiscalPeriodStatus":"OPEN",
          "periodType":"MONTHLY",
          "startDate":"2017-03-01",
          "endDate":"2017-03-31",
          "id":"6c7d0b13-96b9-4d76-a083-4d38c96144e2",
          "spendDate":null,
          "fiscalYearId":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
          "currentPeriod":false
        }
      ],
      "quarterlyFiscalPeriods":[
        {
          "name":"2017-Special - Q1",
          "fiscalPeriodStatus":"OPEN",
          "id":"5ce25dfd-8b2b-4fea-91eb-f8f9ad0bb896 ",
          "periodType":"QUARTERLY",
          "startDate":"2017-01-01",
          "endDate":"2017-03-31",
          "spendDate":null,
          "fiscalYearId":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
          "currentPeriod":false
        },
        {
        "name":"2017-Special - Q2",
        "fiscalPeriodStatus":"OPEN",
        "id":"5ce25dfd-8b2b-4fea-91eb-f8f9ad0bb896 ",
        "periodType":"QUARTERLY",
        "startDate":"2017-04-01",
        "endDate":"2017-06-30",
        "spendDate":null,
        "fiscalYearId":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
        "currentPeriod":false
      },
      {
        "name":"2017-Special - Q3",
        "fiscalPeriodStatus":"OPEN",
        "id":"5ce25dfd-8b2b-4fea-91eb-f8f9ad0bb896 ",
        "periodType":"QUARTERLY",
        "startDate":"2017-07-01",
        "endDate":"2017-09-30",
        "spendDate":null,
        "fiscalYearId":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
        "currentPeriod":false
      },
      {
        "name":"2017-Special - Q4",
        "fiscalPeriodStatus":"OPEN",
        "id":"5ce25dfd-8b2b-4fea-91eb-f8f9ad0bb896 ",
        "periodType":"QUARTERLY",
        "startDate":"2017-10-01",
        "endDate":"2017-12-31",
        "spendDate":null,
        "fiscalYearId":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
        "currentPeriod":false
      }
      ],
      "yearlyFiscalPeriods":[
        {
          "name":"2017-Special",
          "fiscalPeriodStatus":"OPEN",
          "id":"a6bede66-4f3d-412f-a620-2a073013cb2a",
          "periodType":"YEARLY",
          "startDate":"2017-01-01",
          "endDate":"2017-12-31",
          "spendDate":null,
          "fiscalYearId":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
          "currentPeriod":false
        }
      ],
      "customFiscalPeriods":[],
    }
  }

POST a Budget Item

Save a new budget or update an existing budget.

Scopes

budgetitem.write - Refer to Scope Usage for full details.

Request

URI

Template
POST  /budget/v4/budgetItemHeader

Parameters

N/A

Headers

Payload

Budget Item Header

Response

Status Codes

Headers

Response Headers

Payload

Budget Item Response or Error Response

Example

Request

POST https://us.api.concursolutions.com/budget/v4/budgetItemHeader
Authorization: Bearer {token}

Quarterly Budget Example

  {
    "name":"Marketing-US-Jean Normandy",
    "isTest":false,
    "budgetItemStatusType":"OPEN",
    "description":"Marketing-US",
    "id":"72eee673-3d81-49c2-966a-b63c7a9302e6",
    "costObjects":[
      {
      "fieldDefinitionId":"86eee673-3d81-49c2-966a-b63c7a9302e2",
      "code": "6",
      "value": "2",
      "listKey": "1334",
      "operator": "EQUAL",
      "displayName":"Country Code"
    }
    ],
    "periodType":"QUARTERLY",
    "currencyCode":"EUR",
    "budgetCategory":{
      "id":"27451c2d-9121-44bd-b4b0-f2119d2071c7"
    },
    "owner":{
      "externalUserCUUID":"8002250890004822936",
      "employeeUuid":"210fe25f-e326-495c-847a-de333173f616",
      "email":"jean.normandy@xyz.com",
      "employeeId":"jean.normandy"
     },
    "budgetApprovers":[
      {
        "externalUserCUUID":"5005380230004873464",
        "employeeUuid":"eb6082b0-3a9a-4e79-a350-e6e067f34969",
        "email":"dan.lee@xyz.com",
        "employeeId":"dan.lee"
      }
    ],
    "budgetManagers":[
      {
        "externalUserCUUID":"1563846384638464842",
        "employeeUuid":"13a13839-68d6-4ee8-90e9-58604278aa8f",
        "email":"walter.gupta@xyz.com",
        "employeeId":"walter.gupta"
      }
    ],
    "budgetType": "PERSONAL_USE",
    "budgetViewers":[
      {
        "externalUserCUUID":"5005380230004873464",
        "employeeUuid":"eb6082b0-3a9a-4e79-a350-e6e067f34969",
        "email":"dan.lee@xyz.com",
        "employeeId":"dan.lee"
      }
    ],
    "budgetItemDetails":[
      {
        "budgetItemHeaderId":"72eee673-3d81-49c2-966a-b63c7a9302e6",
        "budgetName":"Marketing-US-Jean Normandy",
        "currencyCode":"EUR",
        "amount":2500.00000000,
        "id":"4c165d40-804f-4aaa-b900-a46538537f6a",
        "budgetItemDetailStatusType":"OPEN",
        "fiscalPeriod":{
          "id":"b9659f8a-4e74-4531-9e23-1222ab1507f2"
        }
      },
      {
        "budgetItemHeaderId":"72eee673-3d81-49c2-966a-b63c7a9302e6",
        "budgetName":"Marketing-US-Jean Normandy",
        "currencyCode":"EUR",
        "amount":2500.00000000,
        "id":"0a2dc181-389e-4c85-bb57-e4f1a11ace4e",
        "budgetItemDetailStatusType":"OPEN",
        "fiscalPeriod":{
          "id":"590d4e22-40be-43cc-ac1b-01b0d0263e19"
        }
      },
      {
        "budgetItemHeaderId":"72eee673-3d81-49c2-966a-b63c7a9302e6",
        "budgetName":"Marketing-US-Jean Normandy",
        "currencyCode":"EUR",
        "amount":2500.00000000,
        "id":"35d7dc8a-5ec8-4d5f-ba7c-d9304f7afee3",
        "budgetItemDetailStatusType":"OPEN",
        "fiscalPeriod":{
          "id":"09cd5be1-a21d-47f2-b6b5-8d9019709327"
        }
      },
      {
        "budgetItemHeaderId":"72eee673-3d81-49c2-966a-b63c7a9302e6",
        "budgetName":"Marketing-US-Jean Normandy",
        "currencyCode":"EUR",
        "amount":2500.00000000,
        "id":"4ec30f7c-e7fa-4832-9134-85bed9a85b9c",
        "budgetItemDetailStatusType":"OPEN",
        "fiscalPeriod":{
          "id":"c3beec03-a096-4a33-b7af-b49127742702"
        }
      }
    ],
    "fiscalYear":{
      "id":"a4f9d57f-14ac-4f03-b5aa-4256e5cff790"
    }
  }

Date Range Budget Example

  {
    "name":"Marketing-US-Jean Normandy Date Range",
    "isTest":false,
    "budgetItemStatusType":"OPEN",
    "description":"Marketing-US",
    "id":"72eee673-3d81-49c2-966a-b63c7a9302e6",
    "costObjects":[
     {
      "code": "6",
      "fieldDefinitionId": "86eee673-3d81-49c2-966a-b63c7a9302e2",
      "value": "2",
      "listKey": "1334",
      "operator": "EQUAL",
      "displayName": "Country Code"
    }
    ],
    "periodType":"DATE_RANGE",
    "currencyCode":"EUR",
    "budgetCategory":{
      "id":"27451c2d-9121-44bd-b4b0-f2119d2071c7"
    },
    "owner":{
      "externalUserCUUID":"8002250890004822936",
      "employeeUuid":"210fe25f-e326-495c-847a-de333173f616",
      "email":"jean.normandy@xyz.com",
      "employeeId":"jean.normandy"
     },
    "budgetApprovers":[
      {
        "externalUserCUUID":"5005380230004873464",
        "employeeUuid":"eb6082b0-3a9a-4e79-a350-e6e067f34969",
        "email":"dan.lee@xyz.com",
        "employeeId":"dan.lee"
      }
    ],
    "budgetManagers":[
      {
        "externalUserCUUID":"1563846384638464842",
        "employeeUuid":"13a13839-68d6-4ee8-90e9-58604278aa8f",
        "email":"walter.gupta@xyz.com",
        "employeeId":"walter.gupta"
      }
    ],
    "budgetType": "PERSONAL_USE",
    "budgetViewers":[
      {
        "externalUserCUUID":"5005380230004873464",
        "employeeUuid":"eb6082b0-3a9a-4e79-a350-e6e067f34969",
        "email":"dan.lee@xyz.com",
        "employeeId":"dan.lee"
      }
    ],
    "budgetItemDetails":[
      {
        "budgetItemHeaderId":"72eee673-3d81-49c2-966a-b63c7a9302e6",
        "budgetName":"Marketing-US-Jean Normandy",
        "currencyCode":"EUR",
        "amount":2500.00000000,
        "id":"4c165d40-804f-4aaa-b900-a46538537f6a",
        "budgetItemDetailStatusType":"OPEN",
        "fiscalPeriod":{
          "id":"b9659f8a-4e74-4531-9e23-1222ab1507f7"
        }
      }
    ],
    "fiscalYear":{
      "id":null
    }
  }

Response

Success Response
HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 97
concur-correlationid: 809a0898-e523-4114-950d-bd22705a3b25
  {
    "success": true,
    "budgetItemHeaderId": "72eee673-3d81-49c2-966a-b63c7a9302e6"
  }
Failure Response
HTTP/1.1 400 Bad Request
Cache-Control: no-store
Connection: close
Content-Length: 459
Content-Type: application/json;charset=utf-8
Date: Fri, 21 Sep 2018 15:27:05 GMT
Expires: Thu, 20 Sep 2018 15:27:05 GMT
Pragma: no-cache
concur-correlationid: cea62849-02e5-4a7f-a576-68280c84bd02
{
  "status" : false,
  "errorMessageList" : [
    {
      "errorType" : "ERROR",
      "errorCode" : "BUDGET.BUDGET_ITEM_NAME_REQUIRED",
      "errorMessage" : "Budget item name is required"
    },
    {
      "errorType" : "ERROR",
      "errorCode" : "BUDGET.BUDGET_ITEM_NAME_ERROR",
      "errorMessage" : "Budget item name should be more than 1 characters"
    },
    {
      "errorType" : "ERROR",
      "errorCode" : "BUDGET.BUDGET_ITEM_OWNER_REQUIRED",
      "errorMessage" : "Budget item owner is required"
    }
  ]
}

DELETE a Budget Item Header

Delete a budget item.

Scopes

budgetitem.write - Refer to Scope Usage for full details.

Request

URI

Template
DELETE  /budget/v4/budgetItemHeader/{id}

Parameters

Name Type Format Description
id string path The budget item header's key field.

Headers

Response

Status Codes

Headers

Response Headers

Payload

Budget Item Response or Error Response

Example

Request

DELETE https://us.api.concursolutions.com/budget/v4/budgetItemHeader/72eee673-3d81-49c2-966a-b63c7a9302e6
Authorization: Bearer {token}

Response

HTTP/1.1 200 OK
Cache-Control: no-store
Connection: keep-alive
Content-Length: 97
Content-Type: application/json;charset=utf-8
Date: Fri, 21 Sep 2018 15:24:27 GMT
Expires: Thu, 20 Sep 2018 15:24:27 GMT
Pragma: no-cache
Vary: Origin
concur-correlationid: 86a0d9fe-9e98-43c3-89d8-a2917dd844cb
  {
    "success": true,
    "budgetItemHeaderId": "72eee673-3d81-49c2-966a-b63c7a9302e6"
  }

Schema

PagedBudgetItemHeaderList

Name Type Format Description
totalRows integer - The total number of rows available.
offset integer - The starting row for this page of results (zero-based).
limit integer - The number of results returned per page. Maximum: 50
budgetItemHeaders array budgetItemHeader List of budget item headers. Each budget item header represents a single budget for a fiscal year.
href string - The link to this page of results.
previous string href The href for the previous page of results (null if this is the first page of results).
next string href The href for the next page of results (null if no results remaining).

BudgetItemHeader

Name Type Format Description
active boolean - READ ONLY Indicates if this budget should be displayed on user screens.
annualBudget decimal - READ ONLY The total budget amount and accumulated balances for this budget header.
budgetAmounts array budgetAmounts READ ONLY The accumulated budget amounts for this budget.
budgetManagers array budgetPerson If managers exist, spend items only matches this budget if one of the managers is in the manager hierarchy of the submitter or approver for the given spend item.
budgetApprovers array budgetPerson The workflow approvers for this budget.
budgetCategory array budgetCategory The budget category for this budget item. If a budget category is present, spending items must match one of the expense types in the budget category in order to match this budget.
budgetItemDetails array budgetItemDetail Required Specify the budget information for each fiscal period in the fiscal year.
budgetItemStatusType string - The status of this budget item. Supported values: OPEN, CLOSED(no spending can be attached to this budget), REMOVED
budgetType string - The budget type indicates if the budget item is personal or not. Supported values: PERSONAL_USE, BUDGET, RESTRICTED
budgetViewers array budgetPerson The users who can view this budget.
costObjects array budgetTrackingValue The cost object list for matching spending items.
createdDate date YYYY-MM-DD READ ONLY The time the budget item header was created. Date in UTC.
currencyCode string - The 3-letter ISO 4217 currency code for the budget currency. This is the currency code of the budget amount. Spending Items are converted using yesterday's closing value. Examples: USD - US dollars; BRL - Brazilian real; CAD - Canadian dollar; CHF - Swiss franc; EUR - Euro; GBO - Pound sterling; HKD - Hong Kong dollar; INR - Indian rupee; MXN - Mexican peso; NOK - Norwegian krone; SEK - Swedish krona.
description string - Required The user-friendly name for this budget. This description is displayed to end users on desktop and mobile.
dateRange dateRange - READ ONLY Specify custom date range for budget.
fiscalYear array fiscalYear Required The fiscal year for this budget. Only the ID of the fiscal year, which can be retrieved from the Fiscal Year service, is required for creating/updating a budget.
fiscalYearId string - The unique identifier of the fiscal year for this budget.
id string - The key for this object.
isTest boolean - The test flag for the budget item. If true, this budget will only match spending submitted by test users.
lastModifiedDate dateRange - READ ONLY The last time the budget item header was updated. Date in UTC.
name string - Required The admin-facing name for this budget.
owned string - READ ONLY A flag indicating if the current user is the owner of this budget.
owner array budgetPerson Required The user who is ultimately responsible for this budget.
periodType string - READ ONLY The type of period within the fiscal year that this budget's details use.

BudgetItemDetail

Name Type Format Description
amount decimal - Required The budget currency amount allocated to this fiscal period. May be zero.
budgetAmounts array budgetAmounts READ ONLY The accumulated budget numbers for this budget.
budgetItemBalances array budgetItemBalance READ ONLY Shows the break-out of budget spending by product and workflow state.
budgetItemDetailStatusType string - The status of this budget item. Supported values: OPEN, CLOSED(no spending can be attached to this budget), REMOVED
currencyCode string - The 3-letter ISO 4217 currency code for the budget currency. Examples: USD - US dollars; BRL - Brazilian real; CAD - Canadian dollar; CHF - Swiss franc; EUR - Euro; GBO - Pound sterling; HKD - Hong Kong dollar; INR - Indian rupee; MXN - Mexican peso; NOK - Norwegian krone; SEK - Swedish krona.
budgetName string - READ ONLY The admin-facing name of this budget.
budgetItemHeaderId string - READ ONLY The unique ID of the header that contains this budget item detail.
fiscalPeriod fiscalPeriod - Required The fiscal period for this budget amount. Only the ID of the fiscal period, which can be retrieved from the Fiscal Year service, is required for creating/updating a budget.
detailDashboardBudgetItemAdjustmentDTOs array detailDashboardBudgetItemAdjustment READ ONLY List of budget adjustments.
fiscalPeriod array fiscalPeriod Required The specific fiscal period when this budget amount will be used. Only the ID of the fiscal period, which can be retrieved from the Fiscal Year service, is required for creating/updating a budget.

BudgetAmounts

Name Type Format Description
adjustedBudgetAmount decimal - READ ONLY The amount adjusted against this budget.
availableAmount decimal - READ ONLY The available amount accumulated against this budget. Uses budget setting to determine which amounts are included to calculate available amount.
consumedPercent decimal - READ ONLY The percentage of the budget that is considered used. Uses budget setting to determine which amounts to include.
pendingAmount decimal - READ ONLY The pending amount accumulated against this budget.
spendAmount decimal - READ ONLY The spent amount accumulated against this budget.
threshold string - READ ONLY The indicator of whether this budget is under the alert limit, equal to or over the alert limit but under the control limit, or equal to or over the control limit. Supported values: UNDER, ALERT, OVER
unExpensedAmount decimal - READ ONLY The amount of unexpensed items like travel bookings, quick expenses, or e-receipts.
unExpensedSettings string - READ ONLY The company's budget setting for unexpensed items. Applies to all budgets for the company. Supported values: SHOW_UNSUBMITTED_EXPENSES_AS_PENDING, SHOW_UNSUBMITTED_EXPENSES_BALANCE, DO_NOT_SHOW_UNSUBMITTED_EXPENSES

BudgetPerson

Provide externalUserCUUID or email or employee ID of the user for looking up the person.

Name Type Format Description
externalUserCUUID string - The unique identifier for this user. This must match the CUUID from the SAP Concur profile service.
name string - READ ONLY The user's name. Provided for convenience.
id string - The budget service's unique identifier for this user.
email string - The email address of the person to lookup.
employeeId string - READ ONLY The employee ID of the person to lookup.
employeeUuid string - The unique identifier for this user. This must match the UUID from the SAP Concur profile service.

BudgetCategory

Name Type Format Description
description string - The list of expense types that this budget category matches.
name string - The admin-facing name for this category.
statusType string - The status of this budget category. Supported values: OPEN, REMOVED
id string - The unique identifier for the budget category.

ExpenseType

Name Type Format Description
featureTypeCode string - Required The product that this expense type applies to: Purchase Request, Invoice (Payment Request), Expense, or Request. Supported values: PURCHASE_REQUEST, PAYMENT_REQUEST, EXPENSE, REQUEST
expenseTypeCode string - Required The alphanumeric code that describes an expense type. (Example: MEALS, AC_CATER) Valid expense type codes are returned by the GET /budgetCategory/expenseType method described in the Budget Category service.
name string - READ ONLY The name for this expense type if it maps to an expense type set up in your SAP Concur product(s).
id string - The budget service's key for this object.

BudgetTrackingValue

Name Type Format Description
code string - The code for the cost object field. This can be used instead of fieldDefinitionId and will take priority if populated. This value can be found for your budget tracking fields you have configured by using the GET All Budget Tracking Fields resource.
value string - The value for the cost object field. The value of this field will be ignored unless the operator field is EQUAL, NOTEQUAL, INLIST, or NOTINLIST. The value of this field can be one or more comma-separated values if the INLIST or NOTINLIST operator is chosen.
listKey string - When setting up the budget, specify the listKey that maps to the value of this list in the SAP Concur list service.
operator string - Required The comparison to use when matching values for this tracking field. Supported values: EQUAL, INLIST, ISBLANK, NOTEQUAL, NOTINLIST, ISNOTBLANK, ISTRUE, ISFALSE, ISNOTTRUE, ISNOTFALSE
fieldDefinitionID string - Required The budget service’s key for this object’s field definition ID. This value can be found for your budget tracking fields you have configured by using the GET All Budget TrackingFields resource.
displayName string - The budget field tracking name.

BudgetItemBalance

Name Type Format Description
amount decimal - READ ONLY The balance amount.
featureTypeCode string - READ ONLY The product type for this balance. Supported values: REQUEST, TRAVEL, EXPENSE, PAYMENT_REQUEST
featureTypeSubCode string - READ ONLY The feature type sub code for this balance. Supported values: QUICK_EXPENSE, ERECEIPT, CREDIT_CARD, PERSONAL_CARD, TRIP, RECEIPT_CAPTURE, BILLING_STATEMENT, MANUAL, NONE, BUDGET_AMOUNT, SPENT_AMOUNT, PENDING_AMOUNT, PRE_AUTHORIZED, PURGE_ADJUSTMENT
workflowState string - READ ONLY Supported values: UNSUBMITTED, UNSUBMITTED_HELD, SUBMITTED, APPROVED, PROCESSED, PAID.
id string - The unique identifier for this particular budget balance bucket..

FiscalYear

Name Type Format Description
currentYear boolean - READ ONLY If true, this is the current fiscal year based on the current date and time. false, if otherwise.
startDate date YYYY-MM-DD Required The start date for this fiscal year. The distance between start date and end date may not be more than two years.
endDate date YYYY-MM-DD Required The end date for this fiscal year. The distance between start date and end date may not be more than two years.
name datetime - Required The name of this fiscal year. Must be unique for this entity.
status string - Required The status of this fiscal year. Supported values: OPEN, CLOSED, REMOVED
id string - The budget service's key for this object.
lastModified datetime - READ ONLY The UTC date and time when this object was last changed.
displayName string - READ ONLY Display name for fiscal year. For date range budget item we use this field to display.
monthlyFiscalPeriods array fiscalPeriod READ ONLY The list of monthly Fiscal Periods in this Fiscal Year. Fiscal periods must complete fill the parent Fiscal Year with no overlaps.
quarterlyFiscalPeriods array fiscalPeriod READ ONLY The list of quarterly Fiscal Periods in this Fiscal Year. If this parameter is not specified, quarterly Fiscal Periods are automatically generated based on the monthly Fiscal Periods supplied.
yearlyFiscalPeriods array fiscalPeriod READ ONLY The list of yearly Fiscal Periods in this Fiscal Year. If this parameter is not specified, one period is created that fills the Fiscal Year.
customFiscalPeriods array fiscalPeriod READ ONLY The list of custom Fiscal Periods in this Fiscal Year. Custom Fiscal Periods are API-only and will not display on user budget dashboards.
openAndClosedFiscalPeriods array fiscalPeriod READ ONLY The list of all Fiscal Periods in this Fiscal Year, sorted by status.
fiscalPeriods array fiscalPeriod READ ONLY The list of all Fiscal Periods in this Fiscal Year.
displayName string - READ ONLY Display name for fiscal year. For date range budget item we use this field to display.

FiscalPeriod

Name Type Format Description
currentPeriod boolean - READ ONLY If true, this is the current fiscal period based on the current time. false, if otherwise.
startDate date YYYY-MM-DD Required The start date for this fiscal period. Must be within the parent fiscal year.
endDate date YYYY-MM-DD Required The end date for this fiscal year. Must be within the parent fiscal year.
name string - Required The name of this fiscal period. Must be unique for this entity.
fiscalPeriodStatus string - Required The status of this fiscal period. Supported values: OPEN, CLOSED, REMOVED
periodType string - Required The type of fiscal period. Supported values: MONTHLY, QUARTERLY, YEARLY, CUSTOM, DATE_RANGE
fiscalYearId string - The key of the parent fiscal year for this fiscal period.
id string - The budget service's key for this object.
spendDate date - READ ONLY If the current date is after this fiscal period's start date, this field shows the current date.

DateRange

Name Type Format Description
startDate date YYYY-MM-DD The start date for the budget.
endDate date YYYY-MM-DD The end date for the budget.

DetailDashboardBudgetItemAdjustment

Name Type Format Description
adjustmentType string - The type of adjustment being made. Only a user reference field. Supported values: BUDGET_BALANCE, FUND_TRANSFER, EXPENSE, PAYMENT_REQUEST, PURCHASE_REQUEST, REQUEST, PURGE_ADJUSTMENT
amount decimal - The value of the amount adjusted (+/-).
amountType string - The amount type of the field. Supported values: QUICK_EXPENSE, ERECEIPT, CREDIT_CARD, PERSONAL_CARD, TRIP, RECEIPT_CAPTURE, BILLING_STATEMENT, MANUAL, NONE, BUDGET_AMOUNT, SPENT_AMOUNT, PENDING_AMOUNT, PRE_AUTHORIZED, PURGE_ADJUSTMENT
description string - The short description of the adjustment.
transactionDate date YYYY-MM-DD The transaction date of adjusted spend. Required when the adjustment is made for amount type. Supported values: SPENT_AMOUNT, PENDING_AMOUNT

BudgetItemResponse

Name Type Format Description
success boolean - True or False for success or failure.
budgetItemHeaderId guid - The key of the created/updated/removed budget item header.

Error Response

Name Type Format Description
status boolean - False if there was an error.
errorMessageList array errorMessage List of all errors detected.

Error Message

Name Type Format Description
errorType String - WARNING or ERROR.
errorCode String - Text code for this error.
errorMessage String - Plain language error message.

Response Headers

Budget v4 - Budget Tracking

This resource is used to retrieve information about Budget's tracking fields for an entity. Every entity may have a specific set of budget tracking fields and every budget may enable any or all of the budget tracking fields. If there are tracking fields associated, the budgets get matched to the product only when the tracking field conditions are met.

GET All Budget Tracking Fields

Retrieve budget tracking fields information that is setup in budget configuration. This information returned here like the field definition ID, is needed if you will be importing budgets with tracking field values using the post budget item resource.

Scopes

This API call requires one of the following scopes:

Request

URI

Template
GET /budget/v4/budgetTrackingField

Parameters

N/A

Headers

Response

Status Codes

Headers

Payload

Budget Tracking Field

Example

Request

GET https://us.api.concursolutions.com/budget/v4/budgetTrackingField
Authorization: Bearer {token}
Content-Type: application/json
Accept: application/json

Response

HTTP/1.1 200 OK
Cache-Control: no-store
Connection: keep-alive
Content-Length: 1371
Content-Type: application/json;charset=utf-8
Date: Fri, 21 Sep 2018 15:24:27 GMT
Expires: Thu, 20 Sep 2018 15:24:27 GMT
Pragma: no-cache
Vary: Origin
concur-correlationid: 86a0d9fe-9e98-43c3-89d8-a2917dd844cb
[
   {
        "budgetTrackingFieldName": "Cost Center",
        "fieldType": "LIST",
        "listSyncGuid": "8652CDF9C12B4051B8D180E20840CE9B",
        "fieldId": "86309e0c-913c-47a5-9bcf-24a05342c718",
        "budgetSequenceNumber": 2,
        "connectedListSequenceNumber": 1,
        "fieldDefinitionId":"19b07cff-4d36-44bd-acfe-befcfa607075"
    },
    {
        "budgetTrackingFieldName": "Company",
        "fieldType": "VARCHAR",
        "listSyncGuid": null,
        "fieldId": "d8f911a1-f298-4c65-b06b-710d482c9c46",
        "budgetSequenceNumber": 1,
        "connectedListSequenceNumber": 1,
        "fieldDefinitionId":"ea2b82f3-ac18-4509-a748-842054f47f5f"
    },
    {
        "budgetTrackingFieldName": "Department",
        "fieldType": "LIST",
        "listSyncGuid": "8652CDF9C12B4051B8D180E2084Q412",
        "fieldId": "c4f721cb-8fc9-48cf-993e-5ea0edefcdbd",
        "budgetSequenceNumber": 3,
        "connectedListSequenceNumber": 1,
        "fieldDefinitionId":"8b09cc4a-0274-4f2e-b223-3179f560c6bf"
    },
    {
        "budgetTrackingFieldName": "Vendor",
        "fieldType": "VARCHAR",
        "listSyncGuid": null,
        "fieldId": "bcc7ba39-a3a0-4267-84f4-1d5b439cce65",
        "budgetSequenceNumber": 5,
        "connectedListSequenceNumber": 1,
        "fieldDefinitionId":"d543d38a-ef64-4585-8151-b2f909b7e2d3"
    },
    {
        "budgetTrackingFieldName": "Region",
        "fieldType": "MLIST",
        "listSyncGuid": "8652CDF9C12B4051B8D180E20840CE9B",
        "fieldId": "a2502b74-e3ce-4b30-a3a4-b6ceb68cf677",
        "budgetSequenceNumber": 6,
        "connectedListSequenceNumber": 1,
        "fieldDefinitionId":"51c46189-110b-4de4-80ac-4cbae48625d6"
    },
    {
        "budgetTrackingFieldName": "Country",
        "fieldType": "VARCHAR",
        "listSyncGuid": null,
        "fieldId": "4ac122ad-8c0b-4076-bd41-49b09d576d5b",
        "budgetSequenceNumber": 4,
        "connectedListSequenceNumber": 1,
        "fieldDefinitionId":"b5017eae-0b99-47df-8e0d-2f908292598a"
    }
]

Schema

Budget Tracking Field

Name Type Format Description
budgetTrackingFieldName string - The budget field tracking name.
fieldType string - The data type of this field or field collection. Supported values: LIST, MLIST, VARCHAR
listSyncGuid string - If the dataType of this item is LIST or MLIST, this is the ID of the list definition from the SAP Concur list service.
fieldId string - The budget service's key for this object.
budgetSequenceNumber integer - The sequence or the order in which the budget tracking field appears in the budget UI. This value can be used instead of fieldDefinitionId when importing budgets with POST resource. The budgetSequenceNumber is the the same as the code field when importing budgets.
connectedListSequenceNumber integer - READ ONLY Indicates the level of the budget tracking field in a connected list.
fieldDefinitionId string - The budget service's key for this object's field definition ID. This value is required when using the Budget Item POST Resource to create or update a new budget using budget tracking fields.

Budget v4 - Fiscal Year

The Fiscal Calendar is used both for Reporting and Budget. A fiscal year can start and end at any date as long as the end date is after the start date and does not span more than two years. Fiscal years cannot overlap. Fiscal periods cannot overlap and are limited to 24 per fiscal year.

GET All Fiscal Years

Retrieve a list of all fiscal years

Scopes

This API call requires one of the following scopes:

Request

URI

Template
GET  /budget/v4/fiscalYear

Parameters

Name Type Format Description
lastModifiedAfter datetime YYYY-MM-DDTHH:MM:SS Use this field if you only want Fiscal Years that were changed after the supplied date. The supplied date will be interpreted in the UTC time zone. If lastModifiedAfter is not supplied, the service will return all Fiscal Years, regardless of modified date. Example: 2016-03-29T16:12:20
includeRemoved boolean query If true, the service will return all Fiscal Years, including those that were previously removed. If not supplied, this field defaults to false.

Headers

Response

Status Codes

Headers

Response Headers

Payload

Fiscal Year

Example

Request

GET https://us.api.concursolutions.com/budget/v4/fiscalYear?lastModifiedAfter=2017-02-27T12:30:00
Authorization: Bearer {token}
Content-Type: application/json

Response

HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 2187
concur-correlationid: ffa4ae0a-f65c-4037-8bfb-8996c3fca28c
[
    {
      "name":"2017",
      "startDate":"2017-01-01",
      "endDate":"2017-12-31",
      "status":"OPEN",
      "id":"5e58b9b1-fed6-4d36-a5a1-a1ed325931d4",
      "lastModified":"2017-03-26 20:53:19",
      "currentYear":false,
      "monthlyFiscalPeriods":[
        {
          "name":"2017 - Aug",
          "fiscalPeriodStatus":"OPEN",
          "id":"a4e94128-c7b7-4561-a57e-1512e59e4896",
          "periodType":"MONTHLY",
          "startDate":"2017-08-01",
          "endDate":"2017-08-31",
          "spendDate":null,
          "fiscalYearId":"5e58b9b1-fed6-4d36-a5a1-a1ed325931d4",
          "currentPeriod":false
        },
        {
          "name":"2017 - Jan",
          "fiscalPeriodStatus":"CLOSED",
          "id":"ab2810f5-f045-45b0-b2b2-8e84bc978e27",
          "periodType":"MONTHLY",
          "startDate":"2017-01-01",
          "endDate":"2017-01-30",
          "spendDate":null,
          "fiscalYearId":"5e58b9b1-fed6-4d36-a5a1-a1ed325931d4",
          "currentPeriod":false
        },
        {
          "Additional fiscal periods removed for brevity": "Additional fiscal periods removed for brevity"
        }
      ],
      "quarterlyFiscalPeriods":[
        {"name":"2017 - Q4",
          "fiscalPeriodStatus":"OPEN",
          "id":"655ffe9d-caca-4f2f-a4a1-e04cfb68fd6e",
          "periodType":"QUARTERLY",
          "startDate":"2017-10-01",
          "endDate":"2017-12-31",
          "spendDate":null,
          "fiscalYearId":"5e58b9b1-fed6-4d36-a5a1-a1ed325931d4",
          "currentPeriod":false
        },
        {
          "Additional fiscal periods removed for brevity": "Additional fiscal periods removed for brevity"
        }
      ],
      "yearlyFiscalPeriods":[
        {
          "name":"2017",
          "fiscalPeriodStatus":"OPEN",
          "id":"2fb8ea93-172a-47a6-9611-44eb75ad547b",
          "periodType":"YEARLY",
          "startDate":"2017-01-01",
          "endDate":"2017-12-31",
          "spendDate":null,
          "fiscalYearId":"5e58b9b1-fed6-4d36-a5a1-a1ed325931d4",
          "currentPeriod":false
        }
      ],
      "customFiscalPeriods":[]
    }
]

GET a Fiscal Year

Retrieve a single fiscal year by ID.

Scopes

This API call requires one of the following scopes:

Request

URI

Template
GET  /budget/v4/fiscalYear/{id}

Parameters

Name Type Format Description
id string uuid The fiscal year's key field.

Headers

Response

Status Codes

Headers

Response Headers

Payload

Fiscal Year

Example

Request

GET https://us.api.concursolutions.com/budget/v4/fiscalYear/5e58b9b1-fed6-4d36-a5a1-a1ed325931d4
Authorization: Bearer {token}

Response

HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 1270
concur-correlationid: 39216840-2808-4c49-8874-e9862d96fdb6
{
  "name":"2017",
  "startDate":"2017-01-01",
  "endDate":"2017-12-31",
  "status":"OPEN",
  "id":"5e58b9b1-fed6-4d36-a5a1-a1ed325931d4",
  "lastModified":"2017-03-26 20:53:19",
  "currentYear":false,
  "monthlyFiscalPeriods":[
    {
      "name":"2017 - Aug",
      "fiscalPeriodStatus":"OPEN",
      "id":"a4e94128-c7b7-4561-a57e-1512e59e4896",
      "periodType":"MONTHLY",
      "startDate":"2017-08-01",
      "endDate":"2017-08-31",
      "spendDate":null,
      "fiscalYearId":"5e58b9b1-fed6-4d36-a5a1-a1ed325931d4",
      "currentPeriod":false
    },
    {
      "name":"2017 - Jan",
      "fiscalPeriodStatus":"CLOSED",
      "id":"ab2810f5-f045-45b0-b2b2-8e84bc978e27",
      "periodType":"MONTHLY",
      "startDate":"2017-01-01",
      "endDate":"2017-01-30",
      "spendDate":null,
      "fiscalYearId":"5e58b9b1-fed6-4d36-a5a1-a1ed325931d4",
      "currentPeriod":false
    },
    {
      "Additional fiscal periods removed for brevity": "Additional fiscal periods removed for brevity"
    }
  ],
  "quarterlyFiscalPeriods":[
    {"name":"2017 - Q4",
      "fiscalPeriodStatus":"OPEN",
      "id":"655ffe9d-caca-4f2f-a4a1-e04cfb68fd6e",
      "periodType":"QUARTERLY",
      "startDate":"2017-10-01",
      "endDate":"2017-12-31",
      "spendDate":null,
      "fiscalYearId":"5e58b9b1-fed6-4d36-a5a1-a1ed325931d4",
      "currentPeriod":false
    },
    {
      "Additional fiscal periods removed for brevity": "Additional fiscal periods removed for brevity"
    }
  ],
  "yearlyFiscalPeriods":[
    {
      "name":"2017",
      "fiscalPeriodStatus":"OPEN",
      "id":"2fb8ea93-172a-47a6-9611-44eb75ad547b",
      "periodType":"YEARLY",
      "startDate":"2017-01-01",
      "endDate":"2017-12-31",
      "spendDate":null,
      "fiscalYearId":"5e58b9b1-fed6-4d36-a5a1-a1ed325931d4",
      "currentPeriod":false
    }
  ],
  "customFiscalPeriods":[],
  "displayName":"2017-Special"
}

POST Fiscal Year(s)

Create or update a list of one or more fiscal years.

Scopes

This API call requires one of the following scopes:

Request

URI

Template
POST  /budget/v4/budgetCategory

Parameters

N/A

Headers

Payload

Fiscal Year

Response

Status Codes

Headers

Response Headers

Payload

Fiscal Year or Error Response

Example

Request

POST https://us.api.concursolutions.com/budget/v4/fiscalYear
Authorization: Bearer {token}
[
  {
    "name":"2017-Special",
    "startDate":"2017-01-01",
    "endDate":"2017-03-31",
    "status":"OPEN",
    "monthlyFiscalPeriods":[
      {
        "name":"2017-Special - Jan",
        "fiscalPeriodStatus":"OPEN",
        "periodType":"MONTHLY",
        "startDate":"2017-01-01",
        "endDate":"2017-01-31"
      },
      {
        "name":"2017-Special - Feb",
        "fiscalPeriodStatus":"OPEN",
        "periodType":"MONTHLY",
        "startDate":"2017-02-01",
        "endDate":"2017-02-28"
      },
      {
        "name":"2017-Special - Mar",
        "fiscalPeriodStatus":"OPEN",
        "periodType":"MONTHLY",
        "startDate":"2017-03-01",
        "endDate":"2017-03-31"
      }
    ],
    "displayName":"2017-Special"
  }
]

Response

Success Response
HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 1270
concur-correlationid: 5c00e59f-d00c-4019-8d3d-47130d8e37b4
[
    {
      "name":"2017-Special",
      "startDate":"2017-01-01",
      "endDate":"2017-03-31",
      "status":"OPEN",
      "id":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
      "lastModified":"2018-03-26 20:54:11",
      "currentYear":false,
      "monthlyFiscalPeriods":[
        {
          "name":"2017-Special - Jan",
          "fiscalPeriodStatus":"OPEN",
          "periodType":"MONTHLY",
          "startDate":"2017-01-01",
          "endDate":"2017-01-31",
          "id":"1929d1d9-6c99-4635-9272-508364193f8f",
          "spendDate":null,
          "fiscalYearId":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
          "currentPeriod":false
        },
        {
          "name":"2017-Special - Feb",
          "fiscalPeriodStatus":"OPEN",
          "periodType":"MONTHLY",
          "startDate":"2017-02-01",
          "endDate":"2017-02-28",
          "id":"41aa7452-e52a-4fd6-9c8a-5b199edeadaf",
          "spendDate":null,
          "fiscalYearId":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
          "currentPeriod":false
        },
        {
          "name":"2017-Special - Mar",
          "fiscalPeriodStatus":"OPEN",
          "periodType":"MONTHLY",
          "startDate":"2017-03-01",
          "endDate":"2017-03-31",
          "id":"6c7d0b13-96b9-4d76-a083-4d38c96144e2",
          "spendDate":null,
          "fiscalYearId":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
          "currentPeriod":false
        }
      ],
      "quarterlyFiscalPeriods":[
        {
          "name":"2017-Special - Q1",
          "fiscalPeriodStatus":"OPEN",
          "id":"5ce25dfd-8b2b-4fea-91eb-f8f9ad0bb896 ",
          "periodType":"QUARTERLY",
          "startDate":"2017-01-01",
          "endDate":"2017-03-31",
          "spendDate":null,
          "fiscalYearId":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
          "currentPeriod":false
        }
      ],
      "yearlyFiscalPeriods":[
        {
          "name":"2017-Special",
          "fiscalPeriodStatus":"OPEN",
          "id":"a6bede66-4f3d-412f-a620-2a073013cb2a",
          "periodType":"YEARLY",
          "startDate":"2017-01-01",
          "endDate":"2017-03-31",
          "spendDate":null,
          "fiscalYearId":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
          "currentPeriod":false
        }
      ],
      "customFiscalPeriods":[],
      "displayName":"2017-Special"
    }
]
Failure Response
HTTP/1.1 400 Bad Request
Cache-Control: no-store
Connection: close
Content-Length: 338
Content-Type: application/json;charset=utf-8
Date: Fri, 21 Sep 2018 15:27:05 GMT
Expires: Thu, 20 Sep 2018 15:27:05 GMT
Pragma: no-cache
concur-correlationid: cb061832-82eb-418e-a968-de6b4ce370ae
{
  "status" : false,
  "errorMessageList" : [
    {
      "errorType" : "ERROR",
      "errorCode" : "BUDGET.FISCAL_YEAR_SDATE_ERROR",
      "errorMessage" : "Fiscal year should have a start date"
    },
    {
      "errorType" : "ERROR",
      "errorCode" : "BUDGET.FISCAL_YEARS_HAVE_GAP",
      "errorMessage" : "Fiscal years should not have gaps between them"
    }
  ]
}

DELETE a Fiscal Year

Delete a fiscal year. Fiscal years that are in use may not be deleted.

Scopes

This API call requires one of the following scopes:

Request

URI

Template
DELETE  /budget/v4/fiscalYear/{id}

Parameters

Name Type Format Description
id string uuid The fiscal years's key field.

Headers

Response

Status Codes

Headers

Response Headers

Example

Request

DELETE https://us.api.concursolutions.com/budget/v4/fiscalYear/a11cfc7c-967f-415f-9b30-23f8ce2dbf69
Authorization: Bearer {token}

Response

HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 1270
concur-correlationid: eb7cf20a-3481-45a5-808c-98b8ef7fe805

Schema

FiscalYear

Name Type Format Description
currentYear boolean - READ ONLY True if this the current fiscal year based on the current date and time, False otherwise.
startDate date YYYY-MM-DD Required The start date for this fiscal year. The distance between start date and end date may not be more than two years.
endDate date YYYY-MM-DD Required The end date for this fiscal year. The distance between start date and end date may not be more than two years.
name datetime - Required The name of this fiscal year. Must be unique for this entity.
status string - Required The status of this fiscal year. Supported values: OPEN, CLOSED, REMOVED
id string - The budget service's key for this object.
lastModified datetime - READ ONLY The UTC date and time when this object was last changed.
monthlyFiscalPeriods array fiscalPeriod Required The list of monthly fiscal periods in this fiscal year. Fiscal periods must complete fill the parent fiscal year with no overlaps.
quarterlyFiscalPeriods array fiscalPeriod READ ONLY The list of quarterly fiscal periods in this fiscal year. If this parameter is not specified, quarterly fiscal periods are automatically generated based on the monthly fiscal periods supplied.
yearlyFiscalPeriods array fiscalPeriod READ ONLY The list of yearly fiscal periods in this fiscal year. If this parameter is not specified, one period is created that fills the fiscal year.
customFiscalPeriods array fiscalPeriod READ ONLY The list of custom fiscal periods in this fiscal year. Custom fiscal periods are API-only and will not display on user budget dashboards.
openAndClosedFiscalPeriods array fiscalPeriod READ ONLY The list of all fiscal periods in this fiscal year, sorted by status.
fiscalPeriods array fiscalPeriod READ ONLY The list of all fiscal periods in this fiscal year.
displayName string - READ ONLY Display name for fiscal year. For date range budget item we use this field to display.

FiscalPeriod

Name Type Format Description
currentPeriod boolean - READ ONLY True if this the current fiscal period based on the current date and time, False otherwise.
startDate date YYYY-MM-DD Required The start date for this fiscal period. Must be within the parent fiscal year.
endDate date YYYY-MM-DD Required The end date for this fiscal year. Must be within the parent fiscal year.
name string - Required The name of this fiscal period. Must be unique for this entity.
fiscalPeriodStatus string - Required The status of this fiscal period. Supported values: OPEN, CLOSED, REMOVED
periodType string - Required The type of fiscal period. Supported values: MONTHLY, QUARTERLY, YEARLY, CUSTOM
fiscalYearId string - The key of the parent fiscal year for this fiscal period.
id string - The budget service's key for this object.
spendDate date - READ ONLY If the current date is after this fiscal period's start date, this field shows the current date.

Error Response

Name Type Format Description
status boolean - False if there was an error.
errorMessageList array errorMessage List of all errors detected.

Error Message

Name Type Format Description
errorType String - WARNING or ERROR.
errorCode String - Text code for this error.
errorMessage String - Plain language error message.

Response Headers

CALLOUTS

Callouts and Application Connectors

Overview

Callouts from SAP Concur allow clients to add an interaction with an outside system to their users' SAP Concur experience. The callouts require a web application, called an application connector, which SAP Concur will contact when appropriate. Application connectors can be hosted on the client's site or on a third-party hosting site.

Third-party developers can create callouts to provide SAP Concur clients access to information systems they manage. These developers partner with SAP Concur to have their application connectors reviewed. Once reviewed, applications are available for SAP Concur clients to purchase and configure.

Partner apps that want to use callout services must have their endpoint server(s) added to an SAP Concur safe list. This is done by logging a case with Support to have your host added.

The available callouts are:

Fetch Attendee and Fetch List Item send information out from SAP Concur to an application connector that interfaces with a external system. The connector runs a search on the external system. The results are then returned to SAP Concur, which presents the results to the user.

The Event Notification callout allows clients to receive notification of specific moments in the workflow of an expense report. When a report enters the desired workflow state a request is sent to the external system. The system can call into SAP Concur to get all the details of a report and perform appropriate actions.

The Launch External URL callout gives clients and developers a platform to extend the functionality of SAP Concur, providing a means to deliver custom user interactions, or access functionality found in an external system.

The client can arrange to add an Expense Entry form field that is configured to use the Launch External URL callout to a Concur Expense Entry form. Concur Expense will display this field with an attached button that launches a separate window when clicked. The window is controlled by an application connector, created by the client, a third party developer, or SAP Concur. The application connector is a web server that presents information in the window.

The application connector can access SAP Concur data through the web services, or can access data in an external system. Once the user has completed their actions in the window (such as performing a search or completing a wizard), he/she clicks a button such as "Done" that indicates he/she has concluded their work in the window. The application connector then closes the window.

The application connector can use web services to send information to SAP Concur, to update field values on the expense entry form or other form types. The application connector may send the updates before or after the user closes the window. When the user returns to SAP Concur, the page refreshes and the user sees the current values.

Process Flow

A process flow diagram showing flow between SAP Concur and an application connector

Application Connector Management

SAP Concur administrators use the Manage Application Connectors link on the Web Services page under Administration to register, test and enable application connectors.

Specifications

Security

SAP Concur will make calls to the application connector's endpoint using SSL. During configuration, SAP Concur will connect to the application connector to validate that its hostname and access credentials are valid.

SAP Concur will not be able to connect to the application connector until a certificate signed by a Certificate Authority (CA) is installed in the application connector. If you are hosting the application connector, you will need to install the signed certificate before SAP Concur can access the connector.

Authentication

Authenticating to the application connector

Expense passes credentials using HTTP Basic Auth to authenticate with the application connector. By default, these credentials are stored in the appropriate web configuration file for your platform, such as web.xml or web.config. The steps to configure Expense with the credentials are detailed below.

Managing Application Connectors

SAP Concur administrators use the Manage Application Connectors link in Web Services under Administration to register, test and enable application connectors.

User Permission

The Web Services links can be accessed by users with the following permission:

Accessing Application Connector Registration

The Manage Application Connectors link on the Web Services page is used to register, test and enable or disable application connectors.

To Access Application Connector Registration:
  1. On the home page, select Administration.
  2. Select Company.
  3. Select Web Services.
  4. Click Manage Application Connectors. The Application Connector Registration page appears.

Note you must be one of the roles specified in the User Permission section to complete these steps.

Registering an Application Connector

Once a development partner has configured a application connector, it must be registered with SAP Concur.

To Register an Application Connector:
  1. On the Application Connector Registration page, click New. (Please refer to Accessing Application Connector Registration section for how to access this page.)
  2. In the System area, complete all of the required fields.

    Field Description
    Name Enter the name that should appear in the list of connectors.
    Description Enter the description of the function of the connector, such as what back-end system it might connect to.
    Host Name Enter the hostname for the connector. Example: https://{servername}
    User Name Enter the user name required to authenticate with the host. This must be the same as the user name specified in the configuration file for the application connector. Note: the user name must be at least 10 characters and the maximum allowed length is 50 characters.
    Password Enter the password required to authenticate with the host. This must be the same as the password specified in the configuration file for the application connector. Note: the password must be at least 10 characters and the maximum allowed length is 50 characters.
  3. Click Test Connection. SAP Concur will attempt to connect to the test connection endpoint https://(host name)/system/v1.0/testconnection, using a GET method with the supplied credentials as HTTP Basic Authentication. If you have not configured the test connection endpoint, the test will fail.

    Note: A successful Test Connection request is required to set the connector to “Verified” before it can be used for any of the callout services.

  4. In the Services section, select an outbound message or callout that the connector will interact with.

  5. Click Configure. The Configure Service window appears.

  6. Enter the endpoint that the SAP Concur will connect to on the host. Example: /attendee/v1.0/find

  7. Select the Enabled check box if the endpoint is ready for use. Usually you will do this after you have implemented and tested the endpoint in your application connector.

  8. Click Save. The service is configured for your host.

  9. Repeat steps 4-8 for each service to configure.

  10. Click Save.

Modifying an Application Connector Registration

Once an application connector registration has been created, the fields can be modified. Services can be enabled or disabled from the Modify page.

To Modify an Application Connector:
  1. On the Application Connector Registration page, select the desired registration from the list. (Please refer to Accessing Application Connector Registration section for how to access this page.)
  2. Click Modify.
  3. Edit the system fields as necessary.
  4. Click Test Connection to verify your changes.
  5. Edit the services configurations as necessary.
  6. Click Save to return to the Application Connector Registration page.

Deactivating an Application Connector Registration

Application connector registrations can't be removed, but can be deactivated. Connectors are deactivated by setting all the associated services to inactive.

To Deactivate an Application Connector:

  1. On the Application Connector Registration page, select the desired connector. (Refer to the steps above in the Accessing Application Connector Registration section for how to access this page.)
  2. Click Modify.
  3. Select the active Service.
  4. Click Configure.
  5. Clear the Active check box.
  6. Click OK.
  7. Click Save.

Delete notification requests

Delete an event notification.

URI

https://www.concursolutions.com/api/platform/notifications/v1.0/notification/

Request

Request Parameters

notificationID: The unique identifier for the notification. Required.

Example:
https://www.concursolutions.com/api/platform/notifications/v1.0/notification/{notificationID}

URI Source: The URI is returned in the NotificationUrl element of the Response for the Get Notifications by Status function.

Headers

Authorization Header

Authorization header with OAuth token for valid SAP Concur user. Required.

The OAuth consumer must have one of the following user roles in SAP Concur: Company Administrator or Web Services Administrator for Professional, or Can Administer for Standard.

Accept Header

XML Example Request

DELETE https://www.concursolutions.com/api/platform/notifications/v1.0/notification/nOB1KNTDSV0UqiYeTsy6su$praZSogRJB6 HTTP/1.1
Authorization: OAuth {access token}

Response

Content Types

Schema

The response returns an HTTP Status Code as follows:

HTTP Code Description
200 Success Notification successfully deleted.
400 Bad Request The request is malformed. Check the API document and verify the request uses the correct format.
403 Forbidden The OAuth Consumer doesn't have a required role. Check the API documentation to learn the required roles.

Example of Successful Response

HTTPS 200 Success

Event Notification Callout

The Event Notification callout allows clients to choose to be notified through web services when certain actions take place in their SAP Concur company. If the client uses Concur Expense, the supported events are the Expense report entering the Post-Submit or Pre-Extract workflow steps. If the client uses Concur Travel Request, the supported events are the Travel Request entering the Post-Submit or Pre-Extract workflow steps. When the event happens, SAP Concur generates a notification and places it into the notification system queue. When the notification reaches the front of the queue, SAP Concur sends a request to the configured endpoint with event information.

This callout differs from the standard SAP Concur web services in the following ways:

Contents

Process Flow

Process Flow for the Event Notification Callout

Products and Editions

Example Use Case

An example use of this callout is:

  1. A SAP Concur user submits an expense report, triggering an Event Notification.
  2. The notification is placed in a queue and processed in a first come, first served order.
  3. When the notification gets to the front of the queue, it is sent to the endpoint specified by the developer.
  4. The application connector returns the HTTP 200 status code, and the notification is removed from the queue.
  5. The developer uses the Report information to make the Get Expense Report Details request.
  6. The developer uses the additional information to validate some expense report information.
  7. The developer then uses the Post Expense Report Exceptions function to approve the report.

This is one use case for the Event Notification callout, however it can be used for a wide variety of requirements.

Product Restrictions

SAP Concur products are highly configurable, and not all clients will have access to all features.

Partner developers must determine which configurations are required for their solution prior to the review process.

Existing clients can work with Concur Advantage Technical Services to create custom applications that work with their configuration.

Event Notification Process Overview

The configuration process has the following steps:

  1. Third-party developer, client or SAP Concur downloads, installs, configures, and customizes the application connector. The application connector may make requests to the inbound web services.

  2. The developer or the SAP Concur clients registers the application connector.
    Refer to Installation > Process for the detailed steps.

Once the configuration is complete, the callout uses the following process:

  1. The configured event occurs in SAP Concur.
  2. SAP Concur sends the request information to the specified endpoint for the application connector.

Security

SAP Concur will make calls to the application connector's endpoint using SSL. During configuration, SAP Concur will connect to the application connector to validate that its hostname and access credentials are valid.

In the code SAP Concur provides for a sample application connector, credentials are stored in a web configuration file that varies by platform, such as web.xml or web.config. However, if you are hosting the connector, you can customize where and how the credentials are stored by customizing HTTPBasicAuth.java or Authentication.cs.

Expense or Travel Request will not be able to connect to the application connector until a certificate signed by a Certificate Authority (CA) is installed in the application connector. If you are hosting the application connector, you will need to install the signed certificate before SAP Concur can access the connector.

Authentication

Authentication between SAP Concur and the application connector is performed using HTTP Basic Auth. By default, these credentials are stored in the appropriate web configuration file for your platform, such as web.xml or web.config. These credentials are entered in SAP Concur on the Register Application Connector page in Web Services under Administration.

Refer to the Callouts and Application Connectors page for more information.

Functions

Delete Notification

Get Notifications by Status

Post Event Notification Request 

Installation Process

The installation process includes installing the application connector, and registering it with SAP Concur.

  1. The third-party developer or client will create and install the application connector on their web site or a third party hosting site. The connector should be programmed to accept the requests from SAP Concur and provide the documented responses.
  2. The client registers the application connector with SAP Concur:

    1. Log in to SAP Concur as an administrative user.
    2. Select Administration > Web Services.
    3. Click Manage Application Connectors.
    4. Click New.
    5. Fill out the fields:
    Field Description
    Name Enter the name that should appear in the list of connectors.
    Description Enter the description of the function of the connector, such as what back-end system it might connect to.
    Host Name Enter the hostname for the connector. Example: https://{servername}
    User Name Enter the user name required to authenticate with the host. This must be the same as the user name specified in the configuration file for the application connector, using HTTP Basic Auth.
    Password Enter the password required to authenticate with the host. This must be the same as the password specified in the configuration file for the application connector, using HTTP Basic Auth.
    1. In the Services section, select Send Notification.
    2. Click Configure. The Configure Service window appears.
    3. Enter the endpoint that SAP Concur will connect to on your server. Example: /concur/v1.0/notify
    4. Select the Enabled check box if the endpoint is ready for use. Usually you will do this after you have implemented and tested the endpoint in your application connector.
    5. In the Workflows section, select the workflow step for each expense report or travel request workflow that requires notifications. The two supported work steps are "External Validation - Pre-Extract" and "External Validation - Submit".
    6. Click OK.
    7. Click Test Connection. SAP Concur will attempt to access the configured endpoint with the provided user credentials.
    8. Click Save. The application connector is now registered with SAP Concur and enabled.

Responses and Errors

Refer to the HTTP Status Codes page for details of the common responses and errors.

Fetch Attendee Version 2 Callout

The Concur Fetch Attendee version 2.0 callout allows clients to import attendee information from their internal system to SAP Concur when a user is adding attendees to an entry. The SAP Concur service sends the attendee search fields to an application connector, created by the client, a third-party developer, or SAP Concur. The connector is hosted by the client or third-party developer, and has access to the attendee system of record. The connector uses the attendee information sent from SAP Concur to search for all matching attendee records in the client's system. Once the connector has the list of possible matches, it sends the attendee data to SAP Concur. The user sees the list of matches and can select the appropriate attendee for the entry.

This callout differs from the standard SAP Concur web services in the following ways:

Contents

Process Flow

A process flow diagram showing flow between SAP Concur, an application connector, and client's data source

Products and Editions

Product Restrictions

Callout Details

Information on how to download, install, and configure the application connector is included in Callouts > Core Concepts.

Fetch Attendee Process Overview

The configuration process has the following steps:

  1. Client, third party developer, or SAP Concur downloads, installs, configures, and customizes the application connector.
  2. Optional for Professional / Premium Only: Client SAP Concur admin creates a new attendee type to use with the connector.
  3. Client registers the application connector, selecting the attendee types that will use the connector. Once the configuration is complete, the callout uses the following process:
    1. The user selects the appropriate attendee type in the Search Attendees window.
    2. The user enters information into an attendee field and clicks Search.
    3. SAP Concur sends the attendee search field information to the application connector. This request includes all attendee fields, with any blank values formatted as an empty string.
    4. The application connector queries the attendee system of record and returns a list of results to SAP Concur.
      NOTE: The results list is limited to 100 records.
    5. SAP Concur displays the results in the Search Results section of the Search Attendees window.
      NOTE: If the application connector does not respond or returns an error, the user is notified in a popup window within SAP Concur. SAP Concur will not resend the request unless the user manually initiates the search again.
    6. If the user adds the attendees to the entry, the attendee information is saved in SAP Concur.

Security

SAP Concur will make calls to the application connector's endpoint using SSL. During configuration, SAP Concur will connect to the application connector to validate that its hostname and access credentials are valid.

SAP Concur will not be able to connect to the application connector until a certificate signed by a Certificate Authority (CA) is installed in the application connector. You will need to install the signed certificate before SAP Concur can access the connector.

Authentication

Authentication between SAP Concur and the application connector is performed using HTTP Basic Auth. By default, these credentials are stored in the appropriate web configuration file for your platform, such as web.xml or web.config. These credentials are entered in SAP Concur on the Register Application Connector page in Web Services under Administration.

Refer to the Installation Process for more information.

Functions

Version 3.0: Post Attendee Search Request

Installation Process

The installation process includes installing the application connector, and registering it with SAP Concur.

First, the client or third-party developer will create and install the application connector on their web site or a third party hosting site. The connector should be programmed to accept the requests from SAP Concur and provide the documented responses.

During installation, the client or developer will select and configure an externally available endpoint on the host server for SAP Concur to send the attendee search request to.

The client then registers the application connector with SAP Concur:

  1. Log in to SAP Concur as an administrative user.
  2. Select Administration > Web Services.
  3. Click Manage Application Connectors.
  4. Click New.
  5. Fill out the fields according to the Application Connector Fields table shown below.
  6. In the Services section, select Fetch Attendee.
  7. Click Configure. The Configure Service window appears.
  8. Enter the endpoint that the SAP Concur will connect to on your server. Example: /attendee/v2.0/fetch. Note: The endpoint name should contain 'v2.0', otherwise the API defaults to v1.0 and returns a different set of fields.
  9. Select the Active check box if the endpoint is ready for use. Usually you will do this after you have implemented and tested the endpoint in your application connector.
  10. Select the attendee types that will use the application connector. These attendee types will be automatically configured to not allow users to create new attendees manually.
  11. Click OK.
  12. Click Test Connection. SAP Concur will attempt to access the configured endpoint with the provided user credentials.
  13. Click Save. The application connector is now registered with SAP Concur and enabled.

Application Connector Fields

Field Description
Name Enter the name that should appear in the list of connectors.
Description Enter the description of the function of the connector, such as what back-end system it might connect to.
Host Name Enter the hostname for the connector. Example: https://{servername}
User Name Enter the user name required to authenticate with the host. This must be the same as the user name specified in the configuration file for the application connector, using HTTP Basic Auth.
Password Enter the password required to authenticate with the host. This must be the same as the password specified in the configuration file for the application connector, using HTTP Basic Auth.1.0

SAP Concur Configuration

The SAP Concur administrator can select which attendee types use the connector when registering the application connector. These attendee types will be automatically configured to not allow users to create new attendees manually.

Professional/Premium Only: If desired, the administrator can create a new attendee type specifically for use with the connector.

Responses and Errors

Refer to the HTTP Status Codes for details of the common responses and errors.

Fetch List Callout

The Concur Fetch List callout allows clients to import list items from an internal system to Expense when a user is filling out list fields for an expense. The Expense service sends a request for list items to an application connector, created by the client, a third-party developer, or SAP Concur. The connector is hosted by the client or developer, and has access to the list item system of record. The connector uses the list information sent from Expense to search for all matching list items in the system of record. Once the connector has the list items, it sends the data to Expense. The user sees the list items and can select the appropriate item for the expense. When the user saves the expense, the list item is added to the list within Expense.

This callout differs from the inbound SAP Concur web services in the following ways:

Contents

Process Flow

A process flow diagram showing flow between SAP Concur, an application connector, and client's data source

Products and Editions

Product Restrictions

SAP Concur products are highly configurable, and not all clients will have access to all features.

Partner developers must determine which configurations are required for their solution prior to the review process.

Existing clients can work with Concur Advantage Technical Services to create custom applications that work with their configuration.

Concur Expense and Fetch List Configuration

Expense must have a list field configured to use an external source before this callout can be used. The client creates the list, SAP Concur configures it to use the external source, and the client creates the connected list definition if necessary. If using a connected list, Expense Admin creates a connected list definition in Forms and Fields.

To configure a Fetch List callout: 1. Follow the process to create a new Application Connector (refer to Managing Application Connectors) 2. On the Application Connector Registration page (from Manage Application Connectors), select the desired registration from the list. 3. Click Modify. 4. On the Sytem page under Services, select Fetch List. 5. Click Configure. 6. Add the details of your previously configured list(s): the List Name, List Category, Language Code, and Connected List Leve (if applicable). 7. Click Add List. (Repeat steps 6-7 until all desired lists are added.) 8. Click Active. 9. Click OK.

Note: If this Fetch List callout is made inactive and then subsequently saved on the System page, any lists that have been added to this Fetch List as a Configured List will be deleted from that Fetch List service.

Fetch List Process Overview

Once the configuration is complete, the callout uses the following process:

  1. The user selects the external source list field while creating an expense entry.
  2. Expense sends the list field information and the item codes for the previously selected levels (for connected lists) to the application connector.
  3. The application connector queries the list system of record and returns the set of list items to Expense.
  4. Expense displays the list items in a drop down list.
  5. The user selects the desired list item and saves the expense.

Security

SAP Concur will make calls to the application connector's endpoint using SSL. During configuration, SAP Concur will connect to the application connector to validate that its hostname and access credentials are valid.

In the code SAP Concur provides for a sample application connector, credentials are stored in a web configuration file that varies by platform, such as web.xml or web.config. However, if you are hosting the connector, you can customize where and how the credentials are stored by customizing HTTPBasicAuth.java or Authentication.cs.

Expense will not be able to connect to the application connector until a certificate signed by a Certificate Authority (CA) is installed in the application connector. You will need to install the signed certificate before SAP Concur can access the connector.

Authentication

Authentication between SAP Concur and the application connector is performed using HTTP Basic Auth. By default, these credentials are stored in the appropriate web configuration file for your platform, such as web.xml or web.config. These credentials are entered in SAP Concur on the Register Application Connector page in Web Services under Administration.

Functions

Responses and Errors

Refer to the HTTP Status Codes page for details of the common responses and errors.

Get notifications by status

Retrieves the list of event notifications that are in the supplied status.

Request

Request Parameters

status={status}
The desired status for the notification. Required. Currently supports failed.

Example:
https://www.concursolutions.com/api/platform/notifications/v1.0/notification?status={status}

Headers

Authorization Header

Authorization header with OAuth token for valid SAP Concur user. Required.

The OAuth consumer must have one of the following user roles in SAP Concur: Company Administrator or Web Services Administrator for Professional, or Can Administer for Standard.

Accept Header

Content-Type Header

application/xml

XML Example Request

GET https://www.concursolutions.com/api/platform/notifications/v1.0/notification?status=FAILED HTTP/1.1
Authorization: OAuth {access token}
Accept: application/xml

Response

Supported Content Types

Schema

This request will return a NotificationsList parent element with a Notification child element for each failed notification. The Notification elements will have a Failure child element if the notification is failed.

Failure Elements

Element Description
Context Message that the callout can use to provide the developer some context for the callout.
EventDateTime When the event happened. Format: YYYY-MM-DD:HH:MM:SS
EventType The event that triggered the callout.
NotificationURL The URL the developer calls to delete a failed notification.
ObjectType The type of object that triggered the notification.
ObjectURI The URI for the object. The developer can use the appropriate GET function for the Object Type.

XML Example of Successful Response

HTTP/1.1 200 OK
Content-Length: 626
Content-Type: application/xml

<?xml version="1.0" encoding="utf-8"?>
<NotificationList xmlns="http://www.concursolutions.com/api/notification/2012/06" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
    <Notification>
        <Context i:nil="true" />
        <EventDateTime>2012-11-14T19:45:25</EventDateTime>
        <EventType>Report Entered Expense Report Workflow Step - REPORT SUBMITTED</EventType>
        <NotificationURI>https://www.concursolutions.com/api/platform/notifications/v1.0/notification/nOB1KNTDSWUcJPMV6dPDjNc$scu6EDbt9s</NotificationURI>
        <ObjectType>EXPRPT</ObjectType>
        <ObjectURI>https://www.concursolutions.com/api/expense/expensereport/v1.1/reportfulldetails/nxxKgLlnROzz$sHcpnRHQ$pALxamClaFfdC</ObjectURI>
    </Notification>
</NotificationList>

JSON Example of Successful Response

HTTP/1.1 200 OK
Content-Length: 388
Content-Type: application/json; charset=utf-8

[
  {
    "Context": null,
    "EventDateTime": "2012-11-14T19:45:25",
    "EventType": "Report Entered Expense Report Workflow Step - REPORT SUBMITTED",
    "NotificationURI": "https://www.concursolutions.com/api/platform/notifications/v1.0/notification/nOB1KNTDSWUcJPMV6dPDjNc$scu6EDbt9s",
    "ObjectType": "EXPRPT",
    "ObjectURI": "https://www.concursolutions.com/api/expense/expensereport/v1.1/reportfulldetails/nxxKgLlnROzz$sHcpnRHQ$pALxamClaFfdC"
  }
]

Launch an external URL request v1

SAP Concur will send a request with the information in an encoded query string when the user clicks the button.

Request

URI

The Launch External URL callout launches the URI for the application connector, which can be in a custom location for each client. The standard location is:

https://{servername}/concur/form/v1.0/get

The URI is configured on the Register Application Connector page in Web Services under Administration.

The full URI for the request includes the following query string values:

https://{servername}/concur/form/v1.0/get?xcompanydomain={URL-encoded company domain}
    &xuserid={URL-encoded login ID of interactive user}
    &itemurl={URL-encoded url to item}
    &nonce={URL-encoded timestamp}
    &signature={URL-encoded signature hash}

Request Schema

Value Description
xcompanydomain The company domain.
xuserid The SAP Concur user ID of the logged-in user. This may be an expense delegate instead of the report owner. To get the report owner ID, use the itemurl to get the details of the expense entry, then use those details to get the associated report details, including the report owner ID.
itemurl The URL-encoded URI to access the item the field appears on. An example would be the expense entry URI used by the Expense Report web service.
nonce The URL-encoded GUID used to generate the signature.
signature The URL-encoded signature hash.

Authentication

To authenticate the request, the developer of the page in the application connector will need to generate an auth signature and compare it with the one passed in the query string.

When the request is received by the connector:

  1. Obtain the username and password for the application connector. How you do this will be specific to your implementation. Note: both the username and password must be at least 10 characters for increased security and the maximum allowed length is 50 characters.
  2. Parse and URL decode the following from the query string:
    1. xcompanydomain
    2. xuserid (used for subsequent web service call)
    3. itemurl
    4. nonce
    5. signature (used to authenticate and verify the request)
  3. Base64-decode the provided signature.
  4. Calculate your own base signature string by appending the values as such:
    {xcompanydomain} + {xuserid} + {itemurl} + {connector username} + {connector password} + {nonce}
  5. Use HMacSHA1 to generate a signature hash using the base signature string. To generate the key, concatenate the lower-case value for {connector username} and the exact {connector password}. For example, if the connector user name is JohnDoe, and the password is password, the key would be johndoepassword.
  6. Compare the generated signature hash with the signature hash provided in the request query string. If the signature hashes match then you know the credentials are valid and the request has not been tampered with.

NOTES:

XML Example Request

GET https://{URL to your custom connector and endpoint}
?xcompanydomain={URL-encoded company domain}
    &xuserid={URL-encoded login ID of interactive user}
    &itemurl={URL-encoded url to item}
    &nonce={URL-encoded timestamp}
    &signature={URL-encoded signature hash}

Response

Content Body

The application connector does not directly respond to the Launch External URL request. The application connector completes any updates to SAP Concur using the Inbound Web Services. The Launch External URL functionality monitors the external window, and when the window is closed, it redraws the form the user launched from to display any updated values.

Launch External URL Request v4

Important: This API is currently in pre-release status and is only available to approved early access participants. The API is under development and might change before being generally released. To become an early access participant, contact your SAP Concur Representative.

Launch External URL Request v4

Concur Expense will send a request with the information in an encoded query string when the user clicks the field configured to use the Launch External URL callout.

URI

The Launch External URL V4 callout launches the URI for the application connector, which can be in a custom location for each client. The standard location is:

GET https://{servername}/launchexternalurl/v4/form

The URI is configured on the Register Application Connector page in Web Services under Administration and Company.

The full URI for the request includes the following query string values:

GET https://{servername}/launchexternalurl/v4/form

logged_in_user_id={URL-encoded SAP Concur Unique Identifier of interactive user} report_owner_user_id={URL-encoded SAP Concur Unique Identifier of report owner} report_owner_employee_id={URL-encoded Employee ID (provided by the Client) of report owner} company_domain={URL-encoded company domain} item_url={URL-encoded URL to Header / Entry / Allocation} custom_field_launched_from={Custom Launch External URL form field ID.} expense_ids={URL encoded SAP Concur Entry ID (comma separated) available only for Allocation} source={HEADER/ENTRY/ALLOCATION} is_mobile={Indicates request from mobile UI} signature={URL-encoded signature hash} nonce={URL-encoded signature hash} client_auth_code={URL encoded temporary client authorization code} language_code={URL encoded language code of the logged in user}

Definitions

Value Description
company_domain The client company’s domain.
logged_in_user_id The SAP Concur Universal Unique Identifier (UUID) of the user that is logged into Concur Expense. For example, this may be an expense delegate instead of the report owner.
report_owner_user_id The SAP Concur Universal Unique Identifier (UUID) of the report owner.
report_owner_employee_id The client’s Employee ID of the report owner.
item_url The URL-encoded URI to access the item where the field appears. This URL can be used to get the details of the header, Expense Entry, or Allocation.
custom_field_launched_from The custom Launch External URL form field ID.
expense_ids Concur Expense Entry ID, only used for requests from the Expense Allocation level.
source Context of where the request was made from, either the Expense Report Header, Entry, or Allocation level.
nonce The URL-encoded GUID used to generate the signature.
signature The URL-encoded signature hash.
is_mobile True or false indicating if the end-user is coming from the web-based instance of Concur Expense or mobile. This allows the client to display different UI for mobile devices.
client_auth_code URL encoded temporary client authorization code. This will allow to call OAuth service to get a refresh and access token to access item_url.
language_code Language code of the logged in user. Length between two to five characters. Default is "en". The code may be xx-XX (e.g., en-GB for British English), where xx indicates the base language and correlates to ISO 639-1, and XX specifies the local dialect, if applicable. SAP Concur supported languages are here. Information on language identifiers can be found here in the appendix (Note: a hyphen is the expected separator for this API for languages with dialects, e.g., en-GB).

Authentication

To authenticate the request, the developer of the page in the application connector will need to generate an authentication signature and compare it with the one passed in the query string.

When the request is received by the connector:

  1. Obtain the username and password for the application connector. How you do this will be specific to your implementation.

  2. Parse and URL decode the following from the query string:

    • logged_in_user_id
    • custom_field_launched_from
    • expense_ids
    • source
    • company_domain
    • report_owner_user_id
    • report_owner_employee_id
    • item_url
    • nonce
    • signature (used to authenticate and verify the request)
    • is_mobile
    • client_auth_code
    • language_code
  3. Base64-decode the provided signature.

  4. Calculate your own base signature string by appending the values as such: {company_domain} + {logged_in_user_id} + {report_owner_user_id} + {report_owner_employee_id} + {item_url} + {connector username} + {connector password} + {nonce}

  5. Use HMacSHA1 to generate a signature hash using the base signature string. To generate the key, concatenate the lower-case value for {connector username} and the exact {connector password}. For example, if the connector username is JohnDoe, and the password is password, the key would be johndoepassword.

  6. Compare the generated signature hash with the signature hash provided in the request query string. If the signature hashes match, then you know the credentials are valid and the request has not been tampered with.

NOTES:

URL Example Request

GET https://{URL to your custom connector and endpoint}

?logged_in_user_id={URL-encoded login ID of interactive user}& report_owner_user_id={URL-encoded login ID of the report owner}& company_domain={URL-encoded company domain}& report_owner_employee_id={URL-encoded client’s Employee ID of the report owner}& item_url={URL-encoded url to item}& is_mobile={boolean}& custom_field_launched_from={URL-encoded custom field identifier}& signature={URL-encoded signature hash}& nonce={URL-encoded GUID used to generate the signature}& client_auth_code={URL-encoded auth code}& source={URL-encoded location of the report}& expense_ids={URL-encoded expense IDs if the request came from allocations}& language_code={URL-encoded language code of the logged in user}

Response

Content Body

The application connector does not directly respond to the Launch External URL request. The application connector completes any updates to Concur Expense using the inbound web services. The Launch External URL functionality monitors the external window, and when the window is closed, it redraws the form the user launched from to display any updated values.

Launch External URL v4

Important: This API is currently in pre-release status and is only available to approved early access participants. The API is under development and might change before being generally released. To become an early access participant, contact your SAP Concur Representative.

The Launch External URL callout gives clients and developers the ability to extend the functionality of the SAP Concur platform providing a means to deliver custom user interactions, or access functionality found in an external system. The client can add a Report Header, Expense Entry, or Allocation form field that is configured to use the Launch External URL callout. Concur Expense will display this field with an attached button that launches a separate browser window when clicked. The window is controlled by an application connector, created by a third-party developer or the client. The application connector is a web server that presents information in the window.

The application connector can access SAP Concur data through the web services, or can access data in an external system. Once the user has completed their actions in the window (such as performing a search or completing a wizard), they click a button such as “Done” that indicates the user has concluded their work in the window. Then application connector or user closes the window.

The application connector can use web services to send information to update field values on the Report Header, Expense Entry, or Allocation form types. The application connector may send the updates before or after the user closes the window. When the user returns to the SAP Concur platform, the page refreshes and they see the updated values only if the updates are made before the window is closed.

This callout differs from the standard SAP Concur web services in the following ways:

Prior Versions

The Launch External URL v1 will continue to work only at the Expense Entry level. Launch External URL v1 is not available on the NextGen UI for Concur Expense.

Contents

Process Flow

Process Flow for Launch External Service

Products and Editions

Limitations

SAP Concur products are highly configurable, and not all clients will have access to all features. Partner developers must determine which configurations are required for their solution prior to the review process. Existing clients can work with SAP Concur Integration Services to create custom applications that work with their configuration.

The Launch External URL callout is not supported for expense entry bulk editing. For situations where the data needs to be the same, we recommend configuring Copy-Down of the desired data fields.

Only the Employee role can interact with the Launch External URL configured field. Approver, Expense Processor, and Expense Processor Manager roles will not have access to trigger or interact with the Launch External URL callout configured field. When the Launch External URL field is configured, the Approver, Expense Processor, and Expense Processor Manager roles should be configured as read-only or hidden.

If Expense Assistant is used to create reports and the Launch External URL field is employed at the Report Header level, clients may consider creating a mandatory field for the Report Header to ensure users interact with the Launch External URL field.

If the Launch External URL callout is used in combination with external APIs to retrieve information from the Expense Report Header, Entry, or Allocation, we recommend configuring the Expense Form to have the Launch External URL callout field follow other fields that data will be retrieved from.

The system requires certain named fields (not custom fields) to be completed before a user can trigger the Launch External URL configured field. The system will perform an abbreviated save to make the expense record available to external APIs. These are the fields required to be completed by the end user before the Launch External URL callout can be triggered (if these fields are included and configured as site required on the form):

Any audit rules configured as Save actions will not be visible to the end user until the user returns to the SAP Concur Expense application from the pop-up window.

Callout Details

Information on how to create, install, and configure the application connector is included in Callouts and Application Connectors and below.

Launch URL Process Overview

The configuration process has the following steps:

  1. Third-party developer, client or SAP Concur downloads, installs, configures, and customizes the application connector. The application connector may make requests to the inbound web services.

  2. Concur Expense registers the application connector. Be ready to supply the test and production domain information.

  3. Expense Admin creates a new form field with the Launch External URL control type and adds the field to the Report Header, Expense Entry, or Allocation form(s).

Once the configuration is complete, the callout uses the following process:

  1. The user clicks the button next to the read-only Launch URL form field.

  2. Concur Expense launches a new browser window and sends the Report Header, Entry, or Allocation Details URI, Company Domain, Employee ID, and Unique User ID in an encoded query string to the application connector.

  3. The application connector parses the query string to extract the sent data.

  4. The application connector uses an SAP Concur web service to gather information. This may be Report Header, Expense Entry, or Allocation information.

  5. The application connector presents a web page in the new browser window for the end user. This can be a page from a commercial application, or a custom web application.

  6. The user completes the process in the external system in the browser window.

  7. The application connector sends any field update information to Concur Expense using the SAP Concur web services.

  8. The user or the application connector closes the window and returns to Concur Expense.

  9. Concur Expense reloads the page the user came from in order to display any updated field values (if the application connector sends a value before the window is closed).

Note: Concur Expense will perform a save for the area where the user came from (Entry, Allocation, Header) before the new browser window opens and upon refresh after the window is closed.

Security

Concur Expense will make calls to the application connector’s endpoint using SSL. During configuration, Concur Expense will connect to the application connector to validate that its hostname and access credentials are valid.

Concur Expense provides for a sample application connector, credentials are stored in a web configuration file that varies by platform, such as web.xml or web.config. However, if you are hosting the connector, you can customize where and how the credentials are stored by customizing HTTPBasicAuth.java or Authentication.cs.

Concur Expense will not be able to connect to the application connector until a certificate signed by a Certificate Authority (CA) is installed in the application connector. You will need to install the signed certificate before access.

Authentication

Concur Expense sends requests to the application connector using anonymous authorization (no username and password are provided) over HTTPS.

The application connector can validate the authenticity of the query by generating a signature hash from the provided variables and comparing it with the passed in values, including the signature hash that Concur Expense supplies. Two of the required variables for the signature hash are username and password, which are entered in Concur Expense on the Register Application Connector page in web services under Administration. The application connector must use the same username and password pair to generate its validation signature hash.

Details on registering your client ID can be found on the Authentication Grant page.

Functions

Details of the URI used for the Launch External URL request can be found on the V4 Launch External URL Request page.

Concur Expense Configuration

A custom field in Expense with text data type for the Expense Report Header, Entry, or Allocation must be configured as the Launch URL control type and the form field must be added to the desired form before this callout can be used. The Launch URL control type will not appear in the list until a partner application using the Launch External URL API has been registered and enabled for the company. The administrator must select either a single-line or a multi-line control type, depending on the data that will be placed in the field.

Notes:

Responses and Errors

Refer to the HTTP Codes page for details of the common responses and errors.

Application Connector Management

SAP Concur administrators use the Manage Application Connectors link on the web services page under Administration to register, test, and enable application connectors.

Information on how to create, install, and configure the application connector is included in Callouts and Application Connectors.

Configure Launch External URL - V4 Service

  1. On the Application Connector Registration page, select the desired registration from the list.

  2. Click Modify.

  3. In the Services section, select Launch External URL.

  4. Click Configure. The Configure Service window appears.

  5. Enter a valid URL for the endpoint that Concur Expense will connect to on the host.

  1. Select the Active check box if the endpoint is ready for use. Usually you will do this after you have implemented and tested the endpoint in your application connector.

  2. Click OK. The service is configured for your host.

  3. Click Save, to return to the Application Connector Registration page.

Launch External URL Form Field Configuration

Create a new form field with the Launch External URL control type.

  1. On the Administration link, select Expense, Expense Admin, and Forms and Fields.

  2. Select Form type of the Report Header, Expense Entry, Allocation.

  3. Click the Fields tab.

  4. Select a custom field and click Modify Field. Enter the field information, as example shown below:

  1. Click Save.

  2. Go to the Forms tab and add the Launch URL field to the form.

Note: Make sure the Access Rights are set to Modify for the Employee role. Approver, Expense Processor, and Expense Processor Manager roles should be configured as read-only or hidden.

Launch External URL Callout v1

Limitations: For all new Launch External URL solutions, please use the Launch External URL v4 API.

The Launch External URL callout gives clients and developers a platform to extend the functionality of SAP Concur providing a means to deliver custom user interactions, or access functionality found in an external system. The client can arrange to add an Expense Entry form field that is configured to use the Launch External URL callout to a Concur Expense Entry form. Concur Expense will display this field with an attached button that launches a separate window when clicked. The window is controlled by an application connector, created by a third-party developer, the client, or SAP Concur. The application connector is a web server that presents information in the window.

The application connector can access SAP Concur data through the web services, or can access data in an external system. Once the user has completed their actions in the window (such as performing a search or completing a wizard), he/she clicks a button such as "Done" that indicates the user has concluded their work in the window. The application connector then closes the window. 

The application connector can use web services to send information to SAP Concur to update field values on the expense entry form or other form types. The application connector may send the updates before or after the user closes the window. When the user returns to SAP Concur, the page refreshes and he/she sees the updated values.

This callout differs from the standard SAP Concur web services in the following ways:

Contents

Process Flow

Process Flow for Launch External Service

Products and Editions

Product Restrictions

This callout is not supported in the SAP Concur mobile application.

SAP Concur products are highly configurable, and not all clients will have access to all features.

Only the Employee role can interact with the Launch External URL configured field. Other roles such as the Approver and Processor are not able to trigger the pop-up window.

Partner developers must determine which configurations are required for their solution prior to the review process.

Existing clients can work with SAP Concur Integration Services to create custom applications that work with their configuration.

Callout Details

Information on how to download, install, and configure the application connector is included in Callouts and Application Connectors.

Launch URL Process Overview

The configuration process has the following steps:

  1. Third-party developer, client or SAP Concur downloads, installs, configures, and customizes the application connector. The application connector may make requests to the inbound web services.
  2. SAP Concur registers the application connector. SAP Concur must add the IP address and domain of the application connector to an include list. Be ready to supply the test and production domain information.
  3. Expense Admin creates a new form field with the Launch External URL control type and adds the field to the expense entry form(s).

Once the configuration is complete, the callout uses the following process:

  1. The user clicks the button next to the read-only form field.
  2. Expense launches a new window and sends the Expense Entry Details URI, Company Domain, and X-User ID in an encoded query string to the application connector.
  3. The application connector parses the query string to extract the sent data.
  4. The application connector uses a SAP Concur web service to gather information. This may be expense entry information, user information, or other information.
  5. The application connector presents a web page in the new window for the user to interact with. This can be a page from a commercial application, or a custom web application.
  6. The user completes the external system process. This could be a search, a wizard, or another process.
  7. The application connector sends any field update information to SAP Concur using the SAP Concur web services.
  8. The user or the application connector closes the window and returns to SAP Concur.
  9. SAP Concur reloads the page the user came from in order to display any updated field values.

Security

SAP Concur will make calls to the application connector's endpoint using SSL. During configuration, SAP Concur will connect to the application connector to validate that its hostname and access credentials are valid.

In the code SAP Concur provides for a sample application connector, credentials are stored in a web configuration file that varies by platform, such as web.xml or web.config. However, if you are hosting the connector, you can customize where and how the credentials are stored by customizing HTTPBasicAuth.java or Authentication.cs.

Expense will not be able to connect to the application connector until a certificate signed by a Certificate Authority (CA) is installed in the application connector. You will need to install the signed certificate before SAP Concur can access the connector.

Authentication

SAP Concur sends requests to the application connector using anonymous authorization (no username and password are provided) over HTTPS.

The application connector can validate the authenticity of the query by generating a signature hash from the provided variables and comparing it with the passed in values, including the signature hash that SAP Concur supplies. Two of the required variables for the signature hash are username and password, which are entered in SAP Concur on the Register Application Connector page in Web Services under Administration. The application connector must use the same username and password pair to generate it's validation signature hash. Note: both the username and password must be at least 10 characters for increased security and the maximum allowed length is 50 characters.

Functions

Launch External URL Request

Concur Expense Configuration

An Expense text form field must be configured as the Launch URL control type and the form field must be added to the desired form before this callout can be used. The Launch URL control type will not appear in the list until a partner application using the Launch External URL API has been registered and enabled for the company. The administrator must select either a single-line or a multi-line control type, depending on the data that will be placed in the field.

Notes:

Responses and Errors

Refer to the HTTP Codes page for details of the common responses and errors.  

Post an event notification request

Request

Supported Accept Types

URI

The Event Notification callout sends the notification to a URI for the application connector, which can be in a custom location for each client. The standard location is:

https://{servername}/concur/v1.0/notify

The URI is configured on the Register Application Connector page in** Web Services** under Administration.

Request Headers - Required

Authorization header with Basic authorization for endpoint. Refer to Authentication for more information.

Request Headers - Optional

None

Request Schema

The request will include a Notification parent element, with the following child elements:

Element Description
EventType The event that triggered the callout. Format: Report Entered Expense Report Workflow Step - .
ObjectType The type of object that triggered the notification. Currently supports Expense Report and Travel Request. Format: EXPRPT, TRAVELREQ
ObjectURI The URI for the object. The developer can use the appropriate GET endpoint for the Object Type.
EventDateTime When the event happened. Format: YYYY-MM-DD
Context Message that the callout can use to provide the developer some context for the callout.

XML Example Request

POST /concur/v1.0/notify HTTPS/1.1
Host: www.example.com
Authorization: Basic Y29uY3VyOmNvbmN1cg==
...

<?xml version="1.0" encoding="UTF-8" ?>
<Notification>
    <EventType>Report Entered Expense Report Workflow Step - SUBMIT</EventType>
    <ObjectType>EXPRPT</ObjectType>
    <ObjectURI>https://www.concursolutions.com/api/expense/expensereport/v1.1/reportfulldetails/3%Rek29$wsIY12Di3LS9$gjei%KL23</ObjectURI>
    <EventDateTime>2012-05-01</EventDateTime>
    <Context/>
</Notification>

Response

Supported Content Types

Content Body

The application connector responds with an HTTP 200 code when it successfully receives the notification.

Example of Successful Response

HTTPS 200 Success

Post an attendee search request

Request

URI

The Fetch Attendee version 2.0 callout sends the attendee information to a URI for the application connector, which can be in a custom location for each client. The default is:

https://{servername}/concur/attendee/v2.0/fetch

For backward compatibility, Fetch Attendee version 1.0 is used instead of version 2.0 when the URI uses v1.0 instead of v2.0. The URI is configured on the Application Connector Registration page under Web Services>Administration>Manage Applications.

The application connector responds to the Fetch Attendee request by returning all attendees that match the search criteria. The result is limited to the maximum number of records specified in the request. If more than the maximum number of records are sent, Concur Expense displays a message in the Attendee Search window asking the user to refine their search. The authorization functionality in version 2.0 is the same as version 1.0

Headers

Authorization Header

Required. Authorization header with Basic authorization for endpoint. Refer to Authentication for more information.

Request Schema

The request body contains an AttendeeSearchRequest parent element with an Attendee child element. The Attendee elements contain the values entered on the search form.

Attendee Elements

Element Description
AttendeeTypeCode Code for the attendee type assigned to this attendee. Maximum length is 8 characters.
Company Attendee's company. Also used for Institution Name for Healthcare Provider attendees. Maximum length is 150 characters. Required in the response.
Custom1 through Custom20 Custom fields which vary for a given configuration. Maximum length is 100 characters. Required in the response.

For clients who purchased the HCP Connector, Custom7, Custom8, and Custom9 are mapped to the HCP Attendee Form as follows:
Custom7: License number
Custom8: State of license
Custom9: Healthcare specialty description
Custom21 through Custom25 Custom fields which vary for a given configuration. Maximum length is 100 characters. Required in the response.
For clients who purchased the HCP Connector, Custom15, Custom21, Custom22, and Custom23 are mapped to the HCP Attendee Form as follows:
Custom15: Healthcare practice address
Custom21: Attendee taxonomy
Custom22: Attendee tax ID
Custom23: Covered recipient ID
ExternalID Attendee's unique identifier outside of the SAP Concur solution. Maximum length is 48 characters.
FirstName Attendee's first name. Maximum length is 50 characters.
LastName Attendee's last name. Maximum length is 132 characters.
MaximumNumberRecords Maximum number of records that will be returned to the user for the given search criteria.
MiddleInitial Attendee's middle initial. Maximum length is 1 character.
OwnerLoginID SAP Concur Login ID for the report owner (not the logged in user). The developer can use the User Resource: GET endpoint to obtain user profile details that identify the user and use this information to search for attendees in the system of record for that user.
Suffix Attendee's name suffix. Maximum length is 32 characters.
Title Attendee's title. Maximum length is 32 characters.

XML Example Request

POST /concur/attendee/v1.0/fetch HTTPS/1.1
Host: example.com
Authorization: Basic ...
Content-Type: application/xml; charset=utf-8
Content-Length: {length of content body}

<AttendeeSearchRequest>
    <Attendee>
        <AttendeeTypeCode>BUSGUEST</AttendeeTypeCode>
        <FirstName>Chris</FirstName>
        <MiddleInitial />
        <LastName>Miller</LastName>
        <Suffix />
        <Title>CFO</Title>
        <Company>Len Dev</Company>
        <ExternalID />
        <OwnerLoginID>cm@example.com</OwnerLoginID>
        <MaximumNumberRecords>500</MaximumNumberRecords>
        <Custom1 />
        <Custom2 />
        <Custom3 />
        <Custom4 />
        <Custom5 />
        <Custom6 />
        <Custom7 />
        <Custom8>North America</Custom8>
        <Custom9 />
        <Custom10 />
        <Custom11 />
        <Custom12 />
        <Custom13 />
        <Custom14 />
        <Custom15 />
        <Custom16 />
        <Custom17 />
        <Custom18 />
        <Custom19 />
        <Custom20 />
        <Custom21 />
        <Custom22 />
        <Custom23 />
        <Custom24 />
        <Custom25 />
    </Attendee>
</AttendeeSearchRequest>

Response

Supported Content Types

application/xml

Response Schema

The response will include an AttendeeSearchResponse parent element, with an Attendee child element for each search result.

If no attendees match the search criteria, the response returns an empty AttendeeSearchResponse.

Attendee Elements

The Attendee child element must contain all of the elements described below. The FirstName, LastName, and ExternalID elements must have values. All other elements must be returned in the response, however they can be empty if no data is available.

Element Description
AttendeeTypeCode The attendee type code for the attendee type assigned to this attendee. Maximum length: 8
Company The attendee's company. Required in the response. Also used for Institution Name for Healthcare Provider attendees. Maximum length: 150
Custom1 through Custom25 Varies depending on configuration. Required in the response. Maximum length of Custom1 through Custom20: 100 characters. Maximum length of Custom21 through Custom25: 48 characters. For information about Custom fields that are used by healthcare providers, see the Custom fields for healthcare provider attendees table below.
ExternalID The attendee's unique identifier outside of the SAP Concur solution. Maximum length: 32
FirstName The attendee's first name. Maximum length: 50
LastName The attendee's last name. Maximum length: 132
MiddleInitial The middle initial of the attendee. Maximum length: 1.
Suffix The suffix of the attendee. Maximum length: 32.
Title The attendee's title. Maximum length: 32

Custom Fields for Healthcare Provider Attendees

Field Description
Custom7 License Number
Custom8 State of License
Custom9 Specialty Description
Custom13 Recipient Type/Professional Designation
Custom14 NPI Number
Custom15 Primary Practice Address Line 1
Custom16 Primary Practice Address Line 2
Custom17 Primary Practice Address Line 3
Custom18 Primary Practice City
Custom19 Primary Practice State
Custom20 Primary Practice Zip Code
Custom21 Taxonomy. Max 48 characters.
Custom22 Tax ID. Max 48 characters.
Custom23 Covered Recipient ID. Max 48 characters.

NOTES:

XML Example of Successful Response

HTTPS/1.1 200 OK
Content-Type: application/xml
Content-Length: {length of content body}

<AttendeeSearchResponse>
    <Attendee>
        <ExternalID>1234567890</ExternalID>
        <FirstName>Chris</FirstName>
        <MiddleInitial>T</MiddleInitial>
        <LastName>Miller</LastName>
        <Suffix/>
        <Company>Len Dev</Company>
        <AttendeeTypeCode>BUSGUEST</AttendeeTypeCode>
        <Title>CFO</Title>
        <Custom1/>
        <Custom2/>
        <Custom3/>
        <Custom4/>
        <Custom5/>
        <Custom6/>
        <Custom7>RD</Custom7>
        <Custom8>North America</Custom8>
        <Custom9>Internal Medicine</Custom9>
        <Custom10/>
        <Custom11/>
        <Custom12/>
        <Custom13/>
        <Custom14/>
        <Custom15>100 Main Street, Bellevue, WA 98040</Custom15>
        <Custom16/>
        <Custom17/>
        <Custom18/>
        <Custom19/>
        <Custom20/>
        <Custom21>Tax ID 1234</Custom21>
        <Custom22/>
        <Custom23>Patient ID 576</Custom23>
        <Custom24/>
        <Custom25/>
    </Attendee>
</AttendeeSearchResponse>

The following example shows the expected response when no attendees match the search criteria.

HTTPS/1.1 200 OK
Content-Type: application/xml
Content-Length: {length of content body}

<?xml version="1.0" encoding="utf-8"?>
<AttendeeSearchResponse/>

Post a list search request

Request

Supported Accept Types

application/xml

URI

The Fetch List callout sends the attendee information to a URI for the application connector, which can be in a custom location for each client. The standard location is:

https://{servername}/concur/list/v1.2/fetch

The URI is configured on the Register Application Connector page in Web Services under Administration.

Request Headers - Required

Authorization header with Basic authorization for endpoint. Refer to Authentication for more information.

Request Headers - Optional

None

Request Schema

The request will contain a fetch-list-request parent element, containing the following child elements.

Element Description
long-code The long code is a concatenated string containing the parent list item keys separated by a hyphen (-).
short-code The short code is the key of the parent list item.
query It is possible that the asterisk wildcard will be passed from Expense to the application connector.
  • Asterisk only (*) - Return all items in the list represented by the long code.
  • Text followed by asterisk (West*) - Return all items beginning with the text.
  • Asterisk followed by text - Return all items ending with the text.
search-by Indicates which list item attribute should be searched. Supported values: TEXT, CODE.
NOTE: The application connector must support both attributes in order to properly handle wildcard searches.
lang-code The two character code for the language of the user.
num-to-return Expense will specify the number of items to return. The application connector must use this value to ensure that it does not return more results than requested. There is a system limit of 100 items.
protected-list-key Internal connector information, not used by customers.
list-name Internal connector information, not used by customers.
connector-version Internal connector information, not used by customers.
config-options Internal connector information, not used by customers.
code-by-level Indicates the code at each level in the case of a multi-level list.

XML Example Request for Single Level List

The example uses the Fetch List web service to search a single level list for all projects beginning with Alph, and is configured to connect to an application connector located at www.example.com.

POST /concur/list/v1.2/fetch HTTPS/1.1
Host: example.com
Authorization: Basic ...
Content-Type: application/xml; charset=utf-8
Content-Length: {length of content body}

<?xml version="1.0" ?>
<fetch-list-request>
    <long-code></long-code>
    <short-code></short-code>
    <query>Alph*</query>
    <search-by>TEXT</search-by>
    <lang-code>EN</lang-code>
    <num-to-return>80</num-to-return>
    <protected-list-key />
    <list-name />
    <connector-version />
    <config-options />
</fetch-list-request>

XML Example Request for Multi-Level List

The example uses the Fetch List web service to search a connected list for all cities under US-W-CA (United States, Western Region, California) beginning with San, and is configured to connect to an application connector located at www.example.com.

POST /concur/list/v1.2/fetch HTTPS/1.1
Host: example.com
Authorization: Basic ...
Content-Type: application/xml; charset=utf-8
Content-Length: {length of content body}

<?xml version="1.0" ?>
<fetch-list-request>
    <long-code>US-W-CA</long-code>
    <short-code>CA</short-code>
    <query>San*</query>
    <search-by>TEXT</search-by>
    <lang-code>EN</lang-code>
    <num-to-return>80</num-to-return>
    <protected-list-key />
    <list-name />
    <connector-version />
    <config-options />
    <code-by-level>
        <level1>US</level1>
        <level2>W</level2>
        <level3>CA</level3>      
    </code-by-level>
 </fetch-list-request>

Response

Supported Content Types

application/xml

Response Schema

The application connector responds to the Fetch list web service request by returning all list items that match the search criteria.

The response will include a fetch-list-response parent element, with an item child element for each search result. If there are no search results, the fetch-list-response element is empty. The item child element contains the following child elements:

Element Description
code Required The long code for the list item, consisting of the long code from the request combined with the short code from the response, separated by a hyphen (-).
short-code Required The short code for the list item.
text Required The list item text.
match-value Required The value that matched the search term.

XML Example of Response with Results

HTTPS/1.1 200 OK
Content-Type: application/xml
Content-Length: {length of content body}

<fetch-list-response>
    <item>
        <code>US-W-CA-SF</code>
        <short-code>SF</short-code>
        <text>San Francisco</text>
        <match-value>San Francisco</match-value>
    </item>
    <item>
        <code>US-W-CA-SD</code>
        <short-code>SD</short-code>
        <text>San Diego</text>
        <match-value>San Diego</match-value>
    </item>
    <item>
        <code>US-W-CA-SJ</code>
        <short-code>SJ</short-code>
        <text>San Jose</text>
        <match-value>San Jose</match-value>
    </item>
</fetch-list-response>

XML Example of Response with No Results

HTTPS/1.1 200 OK
Content-Type: application/xml

<fetch-list-response>
</fetch-list-response>

Travel Request Validation

Requests in SAP Concur can be validated in an external system by using a combination of SAP Concur callouts and web services.

This guide provides a step by step overview of how to set up and use the external validation functionality for Requests. This guide does not provide instruction on the process of programming the application connector, but provides an overview of the required functionality.

Step 1 - Create an Application Connector

The application connector is a custom web application that is installed on your company's web server. This application needs to be accessible from outside your company's network, so that SAP Concur can send information to it, and it needs to have access to the system that you are using for validation. The application connector must be configured to accept the event notification requests from SAP Concur. In later steps, you will expand the functionality of the application connector to perform additional tasks. The required connector configuration for this step is:

Once you have the basic application connector functionality set up, you're ready to move to the next step.

Step 2 - Configure Event Notification and Request in SAP Concur

In this step, you will enable the Event Notification functionality in your SAP Concur company in order to receive information about submitted Requests. Then, you will enable the Request API in order to request Request details from SAP Concur.

Before you begin

Procedure: Create the Event Notification Application Connector

  1. Log in to SAP Concur as an administrative user.
  2. Select Administration > Web Services.
  3. Click Manage Application Connectors.
  4. Click New.
  5. Fill out the fields:

|Field|Description| |-----|------| | Name | Enter the name that should appear in the list of connectors. | | Description | Enter the description of the function of the connector, such as what back-end system it connects to. | | Host Name | Enter the hostname for the connector. Example: https://{servername} | | User Name | Enter the user name required to authenticate with the host. This must be the same as the user name specified in the configuration file for the application connector, using HTTP Basic Auth. | | Password | Enter the password required to authenticate with the host. This must be the same as the password specified in the configuration file for the application connector, using HTTP Basic Auth. |
6. In the Services section, select External Report Validation. 7. Click Configure. The Configure Service window appears.
8. Enter the endpoint that the SAP Concur will connect to on your server. Example: /concur/v1.0/notify 9. Select the Enabled check box. 10. In the Workflows section, select the Submit check box for each Request workflow that requires notifications. 11. Click OK. 12. Click Test Connection. SAP Concur will attempt to access the configured endpoint with the provided user credentials. 13. Click Save. The application connector is now registered with SAP Concur and enabled.

Procedure: Create the Request Partner Application

  1. On the Web Services page, click Register Partner Application. The Application Registration page appears.
  2. Click New. The New Partner Application page appears.
  3. Complete all of the required fields:

|Field |Description | |--------|-------| | Name | Enter the name that should appear in the list of applications. | | Description | Enter the description of the function of the application. | | Visibility | This field is only editable by SAP Concur Internal users. | | Active | Select Active. | | APIs Used | Select the Request API. |

  1. The Application Authorization section displays your company domain and automatically creates a Key and Secret to use with this application.
    NOTE: The key and secret allow access to any company that enables this application. You MUST keep this information secret (as specified in the SAP Concur Legal Agreement) to maintain security.
  2. Record the key and secret to use later.
  3. Click OK. The application will automatically be enabled for your company.

You should now begin receiving notifications from SAP Concur when your users submit Requests. In the next step, you'll use the notification data that SAP Concur sends to get the Request information.

Step 3 - Gather the Request Details

In this step, you will expand the application connector functionality to use the data sent by SAP Concur in the event notification to get details about the Request. You'll use the Request details to validate the Request in a later step. The application connector must be updated to perform the following steps, using the SAP Concur web services:

Get OAuth Access Token

All requests to SAP Concur web services must be authenticated using OAuth 2.0.

After receiving an event notification, the application connector should send an HTTP GET request to the Get Access Token using Native Flow function. This function requires the login credentials of an administrative SAP Concur user and the Consumer Key that was generated when you created the partner application in the previous step. Refer to the Get Access Token using Native Flow documentation for the format of the request. SAP Concur will respond to the request with the access token required for the next web service request.

Get Request Details

After you receive the OAuth access token, you are ready to request the Request data. The event notification information that SAP Concur sends includes an element named ObjectURI. The connector can send a GET request to the URI specified in this element, supplying the OAuth access token in the request header in the following format:

GET api/travelrequest/v1.0/requests/nxxKgLlnROz3zHJBCRksaas23dsfs HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
...

Step 4 - Validate the Request Information

In this step, the connector will perform the required validation on the Request information. This step will vary by client. The application connector must be able to access the system(s) used in the validation.

The Request data is validated by the application connector. The validation can produce one of the following results:

In the next step, the application connector will update the Request with the validation results.

Step 5 - Update the Request Workflow

Once the Request has been validated, the application connector is ready to update its workflow. If the Request passed validation, it should be approved, and will then travel forward in its workflow. If the Request did not pass validation, it should be sent back to the employee, which moves it to the beginning of the workflow.

The full Request details include an element named WorkflowStepURL. The application connector posts the workflow action (Approve or Send Back to Employee) to this url, using the same OAuth access token in the header.

SAP Concur responds with a success or failure status, and provides additional information for failures.

The application connector has now completed the process of validating a Request, from the initial notification that a Request was submitted, to the request updating the Request workflow in SAP Concur with the validation results.

Launch External URL Request v4

Launch External URL Request v4

Concur Expense will send a request with the information in an encoded query string when the user clicks the field configured to use the Launch External URL callout.

URI

The Launch External URL V4 callout launches the URI for the application connector, which can be in a custom location for each client. The standard location is:

GET https://{servername}/launchexternalurl/v4/form

The URI is configured on the Register Application Connector page in Web Services under Administration and Company.

The full URI for the request includes the following query string values:

GET https://{servername}/launchexternalurl/v4/form

logged_in_user_id={URL-encoded SAP Concur Unique Identifier of interactive user} report_owner_user_id={URL-encoded SAP Concur Unique Identifier of report owner} report_owner_employee_id={URL-encoded Employee ID (provided by the Client) of report owner} company_domain={URL-encoded company domain} item_url={URL-encoded URL to Header / Entry / Allocation} custom_field_launched_from={Custom Launch External URL form field ID.} expense_ids={URL encoded SAP Concur Entry ID (comma separated) available only for Allocation} source={HEADER/ENTRY/ALLOCATION} is_mobile={Indicates request from mobile UI} signature={URL-encoded signature hash} nonce={URL-encoded signature hash} client_auth_code={URL encoded temporary client authorization code} language_code={URL encoded language code of the logged in user}

Definitions

Value Description
company_domain The client company’s domain.
logged_in_user_id The SAP Concur Universal Unique Identifier (UUID) of the user that is logged into Concur Expense. For example, this may be an expense delegate instead of the report owner.
report_owner_user_id The SAP Concur Universal Unique Identifier (UUID) of the report owner.
report_owner_employee_id The client’s Employee ID of the report owner.
item_url The URL-encoded URI to access the item where the field appears. This URL can be used to get the details of the header, Expense Entry, or Allocation.
custom_field_launched_from The custom Launch External URL form field ID.
expense_ids Concur Expense Entry ID, only used for requests from the Expense Allocation level.
source Context of where the request was made from, either the Expense Report Header, Entry, or Allocation level.
nonce The URL-encoded GUID used to generate the signature.
signature The URL-encoded signature hash.
is_mobile True or false indicating if the end-user is coming from the web-based instance of Concur Expense or mobile. This allows the client to display different UI for mobile devices.
client_auth_code URL encoded temporary client authorization code. This will allow to call OAuth service to get a refresh and access token to access item_url.
language_code Language code from the logged in user's profile (or overriden language from the manually selected language at login for the session). Length between two to five characters. Default is "en". The code may be xx-XX (e.g., en-GB for British English), where xx indicates the base language and correlates to ISO 639-1, and XX specifies the local dialect, if applicable. SAP Concur supported languages are here. Information on language identifiers can be found here in the appendix (Note: a hyphen is the expected separator for this API for languages with dialects, e.g., en-GB).

Authentication

To authenticate the request, the developer of the page in the application connector will need to generate an authentication signature and compare it with the one passed in the query string.

When the request is received by the connector:

  1. Obtain the username and password for the application connector. How you do this will be specific to your implementation. Note: both the username and password must be at least 10 characters for increased security and the maximum allowed length is 50 characters.

  2. Parse and URL decode the following from the query string:

    • logged_in_user_id
    • custom_field_launched_from
    • expense_ids
    • source
    • company_domain
    • report_owner_user_id
    • report_owner_employee_id
    • item_url
    • nonce
    • signature (used to authenticate and verify the request)
    • is_mobile
    • client_auth_code
    • language_code
  3. Base64-decode the provided signature.

  4. Calculate your own base signature string by appending the values as such: {company_domain} + {logged_in_user_id} + {report_owner_user_id} + {report_owner_employee_id} + {item_url} + {connector username} + {connector password} + {nonce}

  5. Use HMacSHA256 to generate its signature (message authentication code) hash using the base signature string. To generate the key, concatenate the lower-case value for {connector username} and the exact {connector password}. For example, if the connector username is "JohnDoe", and the password is "Password", the key would be "johndoePassword".

  6. Compare the generated signature hash with the signature hash provided in the request query string. If the signature hashes match, then you know the credentials are valid and the request has not been tampered with.

NOTES:

URL Example Request

GET https://{URL to your custom connector and endpoint}

?logged_in_user_id={URL-encoded login ID of interactive user}& report_owner_user_id={URL-encoded login ID of the report owner}& company_domain={URL-encoded company domain}& report_owner_employee_id={URL-encoded client’s Employee ID of the report owner}& item_url={URL-encoded url to item}& is_mobile={boolean}& custom_field_launched_from={URL-encoded custom field identifier}& signature={URL-encoded signature hash}& nonce={URL-encoded GUID used to generate the signature}& client_auth_code={URL-encoded auth code}& source={URL-encoded location of the report}& expense_ids={URL-encoded expense IDs if the request came from allocations}& language_code={URL-encoded language code of the logged in user}

Response

Content Body

The application connector does not directly respond to the Launch External URL request. The application connector completes any updates to Concur Expense using the inbound web services. The Launch External URL functionality monitors the external window, and when the window is closed, it redraws the form the user launched from to display any updated values.

Launch External URL v4

The Launch External URL callout gives clients and third-party developers the ability to extend the functionality of the SAP Concur platform providing a means to deliver custom user interactions, or access functionality found in an external system. The client can add a Report Header, Expense Entry, or Allocation form field that is configured to use the Launch External URL callout. Concur Expense will display this field with an attached button that launches a separate browser window when clicked. The window is controlled by an application connector, created by a third-party developer or the client. The application connector is a web server that presents information in the window.

The application connector can access SAP Concur data through the web services, or can access data in an external system. Once the user has completed their actions in the window (such as performing a search or completing a wizard), they click a button such as “Done” that indicates the user has concluded their work in the window. The application connector or user closes the window.

The application connector can use web services to send information to update field values on the Report Header, Expense Entry, or Allocation form types. The application connector may send the updates before or after the user closes the window. When the user returns to the SAP Concur platform, the page refreshes and they see the updated values only if the updates are made before the window is closed.

This callout differs from the standard SAP Concur web services in the following ways:

Contents

Prior Versions

The Launch External URL v1 will continue to work only at the Expense Entry level.

Process Flow

Process Flow for Launch External Service

Products and Editions

Limitations

SAP Concur products are highly configurable, and not all clients will have access to all features. Partner developers must determine which configurations are required for their solution prior to the review process. Existing clients can work with SAP Concur Integration Services to create custom applications that work with their configuration.

The Launch External URL callout is not supported for expense entry bulk editing. For situations where the data needs to be the same, we recommend configuring Copy-Down of the desired data fields.

Only the Employee role can interact with the Launch External URL configured field. Approver, Expense Processor, and Expense Processor Manager roles will not have access to open or interact with the Launch External URL callout configured field. When the Launch External URL field is configured, the Approver, Expense Processor, and Expense Processor Manager roles should be configured as read-only or hidden.

If Expense Assistant is used to create reports and the Launch External URL field is employed at the Report Header level, clients may consider creating a mandatory field for the Report Header to ensure users interact with the Launch External URL field.

If the Launch External URL callout is used as part of a process with other Expense APIs to retrieve information from the Expense Report Header, Entry, or Allocation, we recommend configuring the Expense Form to have the Launch External URL callout field follow other fields that data will be retrieved from (i.e., place the Launch External URL callout field sequentially after the other fields).

The system requires certain named fields (not custom fields) to be completed before a user can open the Launch External URL configured field. The system will perform an abbreviated save to make the expense record available to external APIs. These are the fields required to be completed by the end user before the Launch External URL callout can be opened (if these fields are included and configured as site required on the form):

Any audit rules configured as Save actions will not be visible to the end user until the user returns to the Concur Expense application from the pop-up window.

The Android app is currently in pre-release status and is only available to approved early access participants. To become an early access participant, contact your SAP Concur Representative.

Launch External URL v4 is not currently supported in the China Datacenter.

Launch URL Process Overview

The configuration process has the following steps:

  1. Third-party developer, client or SAP Concur downloads, installs, configures, and customizes the application connector. The application connector may make requests to the inbound web services.

  2. Concur Expense registers the application connector. Be ready to supply the test and production domain information.

  3. Expense Admin creates a new form field with the Launch External URL control type and adds the field to the Report Header, Expense Entry, or Allocation form(s).

Once the configuration is complete, the callout uses the following process:

  1. The user clicks the button next to the read-only Launch URL form field.

  2. Concur Expense launches a new browser window and sends the Report Header, Entry, or Allocation Details URI, Company Domain, Employee ID, and Unique User ID in an encoded query string to the application connector.

  3. The application connector parses the query string to extract the sent data.

  4. The application connector uses an SAP Concur web service to gather information. This may be Report Header, Expense Entry, or Allocation information.

  5. The application connector presents a web page in the new browser window for the end user. This can be a page from a commercial application, or a custom web application.

  6. The user completes the process in the external system in the browser window.

  7. The application connector sends any field update information to Concur Expense using the SAP Concur web services.

  8. The user or the application connector closes the window and returns to Concur Expense.

  9. Concur Expense reloads the page the user came from in order to display any updated field values (if the application connector sends a value before the window is closed).

Note: Concur Expense will perform a save for the area where the user came from (Entry, Allocation, Header) before the new browser window opens and upon refresh after the window is closed.

Security

Concur Expense will make calls to the application connector’s endpoint using SSL. During configuration, Concur Expense will connect to the application connector to validate that its hostname and access credentials are valid.

Concur Expense provides for a sample application connector, credentials are stored in a web configuration file that varies by platform, such as web.xml or web.config. However, if you are hosting the connector, you can customize where and how the credentials are stored by customizing HTTPBasicAuth.java or Authentication.cs.

Concur Expense will not be able to connect to the application connector until a certificate signed by a Certificate Authority (CA) is installed in the application connector. You will need to install the signed certificate before access.

Authorization

Launch External URL V4 uses the Authentication Grant process. When Launch External URL V4 calls are made, and the end-user is already logged into Concur, the customer or third party application will receive a temporary token in the query parameter, "client_auth_code". Since the Launch External URL callout completes the first leg of this 3-legged Oauth2 grant, your application must then exchange the temporary token for a refresh token and access token. For this, please refer to the Authentication Grant page for the POST /oauth2/v0/token details.

Note: users must be logged into their Concur account for this process to work correctly.

Information on the Launch External URL setup is provided in the Configure Launch External URL - V4 Service section below.

Functions

Details of the URI used for the Launch External URL request can be found on the V4 Launch External URL Request page.

Concur Expense Configuration

A custom field in Expense with text data type for the Expense Report Header, Entry, or Allocation must be configured as the Launch URL control type and the form field must be added to the desired form before this callout can be used. The Launch URL control type will not appear in the list until a partner application using the Launch External URL API has been registered and enabled for the company. The administrator must select either a single-line or a multi-line control type, depending on the data that will be placed in the field.

Note: * The Launch External URL currently only works with Professional Edition. * The Launch External URL is available to be configured at the Expense Report Header, Entry, or Allocations-level fields. * This Callout cannot be used with Standard Edition clients or from a Travel or Invoice field.

Responses and Errors

Refer to the HTTP Codes page for details of the common responses and errors.

Application Connector Management

SAP Concur administrators use the Manage Application Connectors link on the web services page under Administration to register, test, and enable application connectors.

Information on how to create, install, and configure the application connector is included in Callouts and Application Connectors.

Note: The application connector must use the same username and password pair to generate its validation signature hash. Both the username and password must be at least 10 characters for increased security and the maximum allowed length is 50 characters.

Configure Launch External URL - V4 Service

Your client ID must first be registered. Details on registering your client ID can be found on the Authentication Grant page. The client ID used for the callout must have the redirect URL registered and the following grants assigned.

Required Grants: refresh_token, password, client_credentials, and authorization_code

No scopes are required to use the Launch External URL callout. However, if the Launch External URL callout is used as part of a process with other Concur APIs, scopes for those other APIs will be needed.

The following steps explain how to register an application connector.

  1. On the Application Connector Registration page, select the desired registration from the list.

  2. Click Modify.

  3. In the Services section, select Launch External URL.

  4. Click Configure. The Configure Service window appears.

  5. Enter a valid URL for the endpoint that Concur Expense will connect to on the host.

  1. Select the Active check box if the endpoint is ready for use. Usually you will do this after you have implemented and tested the endpoint in your application connector.

  2. Ensure the Service Version is set to V4 (only required if moving from V1 to V4).

  3. Enter the Client ID (used to identify your application).

  4. Enter the Redirect URL (base URL from which client will call to get User JWT).

  5. Click OK. The service is configured for your host.

  6. Click Save, to return to the Application Connector Registration page.

Launch External URL Form Field Configuration

Create a new form field with the Launch External URL control type.

  1. Click Administration > Expense > Forms and Fields (left menu).

  2. Select the Form Type of Expense Report Header, Expense Entry, or Expense Allocation.

  3. Click the Fields tab.

  4. Select a custom field and click Modify Field. Enter the field information, as example shown below:

  1. Click Save.

  2. Go to the Forms tab and add the newly created field to the form.

Important Note: Make sure the Access Rights are set to Modify for the Employee role. Approver, Expense Processor, and Expense Processor Manager roles should be configured as read-only or hidden.

CASH-ADVANCE

Cash Advance v4

Important: This API is currently in pre-release status and is only available to approved early access participants. The API is under development and might change before being generally released. To become an early access participant, contact your SAP Concur Representative.

The Cash Advance API can be used to create, view, and issue a cash advance.

Limitations: This API is only available to clients who have been granted access by SAP Concur. Access to this documentation does not provide access to the API. This API is not available for partner or third party use. This API is not available in Implementation environments. Cash Advance APIs supports single Cash Advance Creation, Retrieval and Issuance. Create Cash Advance API currently does not support receipt upload.

Process Flow

Process Flow for Service V2

Products and Editions

Scope Usage

Name Description Endpoint
cashadvance.write Create, Retrieve and Issue a cash advance. GET, POST

Dependencies

The client may use the following SAP Concur APIs to get information: * Identity v4, to retrieve the userId.

Access Token Usage

This API supports user and company level access tokens only.

Create a Cash Advance

Creates a cash advance.

Scopes

cashadvance.write - Refer to Scope Usage for full details.

Request

URI

Template
https://{datacenterURI}/cashadvance/v4/cashadvances
Parameters

None.

Headers

Payload

Response

Status Codes

Payload

Example

Request

  https://us.api.concursolutions.com/cashadvance/v4/cashadvances \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Content-Type: application/json' \
  -H 'concur-correlationid: create-cash-advance-test' \
  -d '{
  "accountCode": "employee account code",
  "amountRequested": {
    "currency": "USD",
    "amount": 100
  },
  "comment": "Cash Advance of local trips",
  "name": "Cash Advance for Chicago",
  "purpose": "Trip to home office",
  "userId": "9FED321D-3484-49F3-A514-84CB2590DFC4"
}

Response

201 Created
{
    "cashAdvanceId": "C0550587A7D7DF4AB41CA8EF72F6F3D1"
}

Retrieve a Cash Advance

Retrieve a cash advance.

Scopes

cashadvance.write - Refer to Scope Usage for full details.

Request

URI

Template
https://{datacenterURI}/cashadvance/v4/cashadvances/{cashAdvanceId}
Parameters
Name Type Format Description
cashAdvanceId string - Required Cash advance ID.

Headers

Response

Status Codes

Payload

Example

Request

  https://us.api.concursolutions.com/cashadvance/v4/cashadvances/C0550587A7D7DF4AB41CA8EF72F6F3D1 \
  -H 'Authorization: Bearer {access_token}' \
  -H 'concur-correlationid: create-cash-advance-test' \
  -d '{
}

Response

200 OK

{
    "paymentType": {
        "description": "Payment in cash",
        "paymentCode": "CASH"
    },
    "exchangeRate": {
        "operation": "MULTIPLY",
        "value": "1.00000000000000"
    },
    "amountRequested": {
        "amount": "100.000000",
        "value": "100.000000",
        "currency": "USD"
    },
    "availableBalance": {
        "amount": "0.0",
        "currency": "USD"
    },
    "approvalStatus": {
        "name": "Not Submitted",
        "code": "C_NOTF"
    },
    "cashAdvanceId": "83C46E6ADBD7D647B1AC34D1C0574E87",
    "requestDate": "2020-10-29 18:28:11.0",
    "name": "Cash Advance for Chicago",
    "purpose": "Trip to home office",
    "issuedDate": null,
    "accountCode": "employee account cod",
    "comment": "Cash Advance of local trips",
    "lastModifiedDate": "2020-10-29 18:28:11.0",
    "hasReceipts": false,
    "reimbursementCurrency": "USD"
}

Issue a Cash Advance

Issues a cash advance.

Scopes

cashadvance.write - Refer to Scope Usage for full details.

Request

URI

Template
https://{datacenterURI}/cashadvance/v4/cashadvances/{cashAdvanceId}/issue
Parameters
Name Type Format Description
cashAdvanceId string - Required Cash advance ID.

Headers

Payload

Response

Status Codes

Payload

Example

Request

  https://us.api.concursolutions.com/cashadvance/v4/cashadvances/C0550587A7D7DF4AB41CA8EF72F6F3D1/issue \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Content-Type: application/json' \
  -H 'concur-correlationid: create-cash-adavance-test' \
  -d '{
  "accountCode": "employee account code",
  "comment": "Issuing Cash Advance of employee local trips",
  "exchangeRate": 1.00000
}

Response

200 OK

{
    "issuedDate": "2020-10-29",
    "status": {
        "code": "C_ISSU",
        "name": "Issued"
    }
}

Schema

Create Cash Advance Request

Name Type Format Description
accountCode string - The account code, if not provided, will be read from the employee profile configuration data. Maximum characters: 48
amountRequested - amount Required The amount of the cash advance.
comment string - Comment while creating a cash advance. Maximum characters: 2000
name string - Required Cash advance name. Maximum characters: 40
purpose string - Purpose of raising a cash advance. Maximum characters: 2000
userID string - Required The unique identifier of the SAP Concur user. Use Identity v4 to retrieve the userID. Maximum characters: 16

Amount

Name Type Format Description
currency string - Required The 3-letter ISO 4217 currency code. Maximum characters: 3
amount number - Required The amount value. Maximum characters: 23

Create Cash Advance Response

Name Type Format Description
cashAdvanceId string - Unique cash advance identifier.

Get Cash Advance Response

Name Type Format Description
paymentType - payment Details on type of the payment used.
exchangeRate - exchangeRate Details on the exchange rate. Maximum characters: 23
amountRequested - amountRequested Details on the amount requested.
availableBalance - availableBalance Details on the available balance.
approvalStatus - approvalStatus Details on the approval status.
cashAdvanceId string - Unique cash advance identifier.
requestDate string YYYY-MM-DD The date the cash advance was requested.
name string - Cash advance name. Maximum characters: 40
purpose string - Purpose of raising a cash advance. Maximum characters: 2000
issuedDate string YYYY-MM-DD The date the cash advance was issued.
accountCode string - Account code linked to the employee.
comment string - Comment while creating a cash advance. Maximum characters: 2000
lastModifiedDate string YYYY-MM-DD The date the cash advance was last modified.
hasReceipts string - If the cash advance has receipts.
reimbursementCurrency string - The 3-letter ISO 4217 currency code. Maximum characters: 3

payment

Name Type Format Description
description string - The payment method for the cash advance.
paymentCode string - The ID of the payment type for the cash advance.

exchangeRate

Name Type Format Description
operation string - Exchange rate operation. Supported values: MULTIPLY
value number - Exchange rate value.

amountRequested

Name Type Format Description
amount number - Requested cash advance amount. Maximum characters: 23
value number - Deprecated (Use amount).
currency number - The 3-letter ISO 4217 currency code. Maximum characters: 3

availableBalance

Name Type Format Description
amount number - Unsubmitted balance. Maximum characters: 23
currency number - The 3-letter ISO 4217 currency code. Maximum characters: 3

approvalStatus

Name Type Format Description
name string - Cash advance status name. Maximum characters: 40
code string - Cash advance status key.

Issue Cash Advance Request

Name Type Format Description
accountCode string - Account code linked to the employee.
comment string - Comment while issuing a cash advance. Maximum characters: 2000
exchangeRate number - The exchange rate that applies to the expected expense.If no exchange rate is provided system exchange rate will be considered. Maximum characters: 23

Issue Cash Advance Response

Name Type Format Description
status - status Details on type of payment used.
issuedDate string YYYY-MM-DD The date the cash advance was issued.

status

Name Type Format Description
code string - Cash advance status key.
name string - Cash advance status name. Maximum characters: 40

Error

Name Type Format Description
errorCode string - The unique identifier of the error.
errorMessage string - Message associated with the error.

COMMON

Connection Requests v3.2

The Connection Requests resource is used to integrate TripLink partner applications with Concur. It can be used to create, update, and manage connections between a user's Concur account and a select travel loyalty program. With Connection Requests a TripLink partner application can retrieve new connection requests in order to match users who want to connect to the supplier with the user's account in the supplier system. After the request is retrieved, the supplier is expected to provide a status if the connection was successful or failed. When retrieving new connections, the results can be filtered by status, page offset, and a limit for the number of records to return.

In version 3.2, connection requests can also associate users to either loyalty programs, Concur verified e-mail addresses, or both of these factors. Concur verified emails are email addresses where a user has taken additional steps to confirm an email belongs to them by entering a verification code within the Concur UI after receiving this in their email. Verified emails have uniqueness across all user accounts in the Concur system.

The use of loyalty numbers and/or verified emails to identify users is based on the business agreement between Concur and the TripLink supplier and will be discussed during the TripLink integration kick-off process. Email or loyalty number will not be returned in the connection request if the supplier is not using these factors in their process to match a user in their system to a Concur user.

Our recommendation for suppliers is to match users requesting to connect utilizing last name and loyalty number only. Or in the case of suppliers without loyalty numbers to use verified email and the last name of the user only. The first name and middle name fields have proved to generate a high degree of failures when utilized due to issues like nicknames within the supplier systems.

GET /api/v3.2/common/connectionrequests/
GET /api/v3.0/common/connectionrequests/  (deprecated)
GET /api/v3.1/common/connectionrequests/  (deprecated)

Parameters

Name Type Format Description
offset query string The starting point of the next set of results, after the limit specified in the limit field has been reached. The default is the beginning of the page.
limit query Int32 The number of records to return. The default is 5 and the maximum is 10.
status query string The status code representing the state of the connection request. The possible values are Pending, Processing, Connected, Failed, and Retry.

Retrieve a connection request by ID

GET /api/v3.2/common/connectionrequests/{id}

GET /api/v3.0/common/connectionrequests/{id} (deprecated) GET /api/v3.1/common/connectionrequests/{id} (deprecated)

Parameters

Name Type Format Description
id path string Required The connection request ID.

Create a connection request on behalf of a specific user

POST /api/v3.2/common/connectionrequests/

POST /api/v3.0/common/connectionrequests/ (deprecated) POST /api/v3.1/common/connectionrequests/ (deprecated)

Parameters

Name Type Format Description
user query string Required The login ID of the user for whom to create the connection request. The user must have the Web Services Admin role to use this parameter.

Update a connection request

PUT /api/v3.2/common/connectionrequests/{id}

PUT /api/v3.0/common/connectionrequests/{id} (deprecated) PUT /api/v3.1/common/connectionrequests/{id} (deprecated)

Parameters

Name Type Format Description
id path string Required The connection request ID.
content body - Required The connection request object to update.

Schema 3.2

Connection Requests

Name Type Format Description
Items array Connection Request The result collection.
NextPage string The URI of the next page of results, if any.

Connection Request

Name Type Format Description
firstName string - The user's first name.
ID string - The unique identifier of the resource.
lastModified string - The date and time when the connection request was last modified. Format: UTC
lastName string - The user's last name.
loyaltyNumber string - The user's travel loyalty number.
middleName string - The user's middle name.
requestToken string - The request token.
status string - The status code representing the state of the connection request.
URI string - The URI to the resource.
userId string - The unique identifier of the user.
emailAddresses UserEmailAddresses User Email Addresses Email addresses associated with the user.

User Email Addresses

Name Type Format Description
email1 string - The user's verified email address.
email2 string - The user's verified email address.
email3 string - The user's verified email address.
email4 string - The user's verified email address.
email5 string - The user's verified email address.

Schema 3.0 (Deprecated)

Connection Requests

Name Type Format Description
Items array Connection Request The result collection.
NextPage string The URI of the next page of results, if any.

Connection Request

Name Type Format Description
FirstName string - The user's first name.
ID string - The unique identifier of the resource.
LastModified string - The date and time when the connection request was last modified. Format: UTC
LastName string - The user's last name.
LoyaltyNumber string - The user's travel loyalty number.
MiddleName string - The user's middle name.
RequestToken string - The request token.
Status string - The status code representing the state of the connection request.
URI string - The URI to the resource.

Schema 3.1 (Deprecated)

Connection Requests

Name Type Format Description
Items array Connection Request The result collection.
NextPage string The URI of the next page of results, if any.

Connection Request

Name Type Format Description
FirstName string - The user's first name.
ID string - The unique identifier of the resource.
LastModified string - The date and time when the connection request was last modified. Format: UTC
LastName string - The user's last name.
LoyaltyNumber string - The user's travel loyalty number.
MiddleName string - The user's middle name.
RequestToken string - The request token.
Status string - The status code representing the state of the connection request.
URI string - The URI to the resource.
EmailAddresses UserEmailAddresses User Email Addresses Email addresses associated with the user.

User Email Addresses

Name Type Format Description
Email1 string - The user's verified email address.
Email2 string - The user's verified email address.
Email3 string - The user's verified email address.
Email4 string - The user's verified email address.
Email5 string - The user's verified email address.

Getting Started

Important: This API is currently in pre-release status and is only available to approved early access participants. The API is under development and might change before being generally released. To become an early access participant, contact your SAP Concur Representative.

Event Subscription Service (ESS)

The Event Subscription Service (ESS) implements Publish/Subscribe pattern using principles of Event Driven Architecture in SAP Concur. It allows clients and partners to be notified through web services when certain actions take place in connected SAP Concur companies. When the business/system event occurs in SAP Concur, ESS sends that event to the configured endpoint with relevant information.

ESS Terminology

ESS Delivery model

It is important to remember that ESS doesn't have any API that you can call for SAP Concur events, ESS delivers events to your endpoint.

Access control

ESS is requiring a caller to have a proper JWT and scopes, for more details please refer our wiki A caller must have types of scopes

All required scopes can be requested for a caller Application by Partner Enablement team.

Subscribing your endpoint

In order to begin receiving events, you must first subscribe to the relevant topic(s) for your application.

To subscribe to an event, you must work with your relevant SAP Concur technical contact; for partners, please work with your technical enablement contact. For customers, your web services consultant will subscribe on your behalf to the relevant topic(s).

Endpoint Requirements

The Event Subscription Service provides guaranteed at least once event delivery.  This is accomplished through retrying posting of the event payload to the subscribers' endpoint until the response indicates successful receipt.  The expected acknowledgment max for a request to the subscribers' endpoint is 30 seconds.  The service will attempt posting to the endpoint and then back-off and retry until the subscriber endpoint responds with delivered or not accepted, the service will retry at least 3 days and skip to the next event after unsuccessful delivery.  SAP Concur suggests the subscriber to consider following: * Endpoint response time requirements depend on the topic throughput. Please contact topic owner to calculate acceptable throughput, generally we recommend to keep response time as low as possible (< 3 seconds) * We highly recommend to implement queue behind the subscriber' endpoint in order to keep response time as low as possible
* The subscriber must maintain reasonable uptime to support the requirements of the integration scenario. * We multithreaded application to deliver events to your endpoint. 24 threads by default. * Your HTTPS server endpoint must be accessible from the public web with a non-self-signed certificate.  The certificate should be signed by a known Certificate Authority and should be reachable through DNS.

ESS Authentication

There are several way how you can be sure that your endpoint being accessed by our service. * We will always use the same client x509 certificate. Common name is "CN=webhook.api.concursolutions.com,O=Concur Technologies\, Inc.,L=Bellevue,ST=Washington,C=US" and certificate serial number is "0AE315A13AB9EF8CADB9A46255C87283" * We will always use Digital Signature, it will be supplied in request header "Concur-Signature". If you decide to use this authentication method you will need our

PUBLIC KEY

-----BEGIN PUBLIC KEY----- MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAxS1LsXrEWEEMPooLHa4r osCAnmkO3HaBAk0YcsDMR6hQeuQNLqRWP65TpbfTbKWmZ22Hzep3Ekhs1qvSZgI+ iq/bnVeDhkcD+LqVQGP+7fyE0E0bO96FOzMmtbRet4wAiiE9+uw5GmZfg+fRG3yI y2N5u5p7VHJ1RwNugrIUQjhrLvZc+lhqR/aKTxQCQ5CGAgLZIcr3FIWCWrSBMK3d Wy3KI+qe3ZX0STrCCNxl2UFnuuAa2RZZ2j4QtWHlNkyK+UEup+cGkvpc1XrT7anL HlbTP6jE7MqB5sJ9r2EEzrJzJZjD13UqlzvI61tTC8SKpuk5AEaSsUV7RKlKUCjB 8wIDAQAB -----END PUBLIC KEY-----

ESS Behavior

The Event Subscription service has the following characteristics from the subscriber perspective:

Event Subscription Management

Event Subscription Management

Important: This API is currently in pre-release status and is only available to approved early access participants. The API is under development and might change before being generally released. To become an early access participant, contact your SAP Concur Representative.

1. Access Control (JWT)

The Event Subscription Service (ESS) APIs uses the standard Concur OAuth2 Framework for Authentication and Authorization via JSON Web Token (JWT).

The authentication is done by using a JWT which represents the event subscriber. This can be obtained by calling the Client Credentials grant type using your OAuth2 credentials. The JWT generated by this grant will have a JWT Type of App where your Application ID is the Subject of the Token.

For authorization, the Application needs to contain the scope events.topic.read in order to access the ESS APIs. This scope will be inherited by the JWT during the Client Credentials Grant which is then checked by the ESS API.

Pass the JWT in the Post Header when making calls to the ESS API: Authorization: Bearer <JWT> The Client Credentials JWT has a lifetime of 60 minutes and can only be obtained again via the Client Credentials Grant.

2. Browse available topics

Before you create any subscription you need to verify that you have sufficient access to the topic. If that request returns empty you need to get in touch with your assigned contact from SAP Concur to set proper scopes to your Concur Oauth2 Application.

Request GET /events/v4/topics Response json ["public.test"]

3. Create a subscription

To create a subscription you need to 1. know and have sufficient access to the topic 1. get your receiving endpoint running, endpoint requirements
1. come up with unique name (id) of your subscription. Subscription names are globally unique, and you will get an error if name is already occupied. 1. set filter to .* (regexp syntax), you can use it later to filter out unwanted types of events

Request PUT /events/v4/subscriptions/webhook json { "id": "my-unique-subscription-id", "filter": ".*", "topic": "public.test", "webHookConfig": { "endpoint": "https://www.concuress.com/sub/my-valid-endpoint" } } Response json {"message":"Subscription 'my-unique-subscription-id' saved successfully"}

4. Verify your subscription

You can always request a configuration of your subscription. You might notice that your subscription contains some more parameters that you can not modify for security reasons, but can use them for troubleshooting purposes. - applicationId - identifies your Concur Application as an owner of that subscription - companyIds - a list of UUIDs of companies that allowed your Applicaion to access their data, the process of connecting Concur company to your application is described here (link) - groups and scope - are used for complex access control scenarios

Request GET /events/v4/subscriptions/my-unique-subscription-id Response json [ { "id": "my-unique-subscription-id", "topic": "public.test", "filter": ".*", "webHookConfig": { "endpoint": "https://www.concuress.com/sub/my-valid-endpoint" }, "applicationId": "dabd27f0-23e7-415d-b5e5-19a7dbe4fb4d", "scope": "", "groups": [], "companyIds": [] } ]

5. Browse existing subscriptions

If you happen to forget your subscription name/id, you can always retrieve all of your subscriptions by calling next endpoint:
Request GET /events/v4/subscriptions Response json [ { "id": "my-second-unique-subscription-id", "topic": "public.test", "filter": ".*", "webHookConfig": { "endpoint": "https://www.concuress.com/sub/my-second-valid-endpoint" }, "applicationId": "dabd27f0-23e7-415d-b5e5-19a7dbe4fb4d", "scope": "", "groups": [], "companyIds": [] }, { "id": "my-unique-subscription-id", "topic": "public.test", "filter": ".*", "webHookConfig": { "endpoint": "https://www.concuress.com/sub/my-valid-endpoint" }, "applicationId": "dabd27f0-23e7-415d-b5e5-19a7dbe4fb4d", "scope": "", "groups": [], "companyIds": [] } ]

6. Delete your subscription

Request DELETE /events/v4/subscriptions/my-unique-subscription-id Response json { "message": "Subscription 'my-unique-subscription-id' marked for deletion" }

6. Request Example

HEADERS PUT /events/v4/subscriptions/webhook HTTP/1.1 Content-Type: application/json Concur-Correlationid: something-unique-and-trackable Authorization: Bearer eyJ0e*****MY-SECRET-JWT-HERE******** Accept: */* Cache-Control: no-cache Host: www-us.api.concursolutions.com Accept-Encoding: gzip, deflate Connection: keep-alive BODY { "id": "my-unique-subscription-example", "filter": ".*", "topic": "public.test", "webHookConfig": {"endpoint": "https://www.concuress.com/sub/my-unique-endpoint" } }

CURL Code curl -X PUT \ https://www-us.api.concursolutions.com/events/v4/subscriptions/webhook \ -H 'Accept: */*' \ -H 'Accept-Encoding: gzip, deflate' \ -H 'Authorization: Bearer eyJ0e*****MY-SECRET-JWT-HERE********' \ -H 'Cache-Control: no-cache' \ -H 'Concur-Correlationid: something-unique-and-trackable' \ -H 'Connection: keep-alive' \ -H 'Content-Type: application/json' \ -H 'Host: www-us.api.concursolutions.com' \ -H 'cache-control: no-cache' \ -d '{ "id": "my-unique-subscription-example-2", "filter": ".*", "topic": "public.test", "webHookConfig": { "endpoint": "https://www.concuress.com/sub/my-unique-endpoint" } }'

Getting Started

Important: This API is currently in pre-release status and is only available to approved early access participants. The API is under development and might change before being generally released. To become an early access participant, contact your SAP Concur Representative.

Overview

The Event Subscription Service (ESS) allows clients and partners to choose to be notified through web services when certain actions take place in connected SAP Concur companies. When the event occurs, SAP Concur generates a notification and sends a request to the configured endpoint with event information.

This callout differs from the standard Concur web services in the following ways:

Subscribing

In order to begin receiving events, you must first subscribe to the relevant topic(s) for your application connector.

To subscribe to an event, you must work with your relevant SAP Concur technical contact; for partners, please work with your technical enablement contact. For customers, your web services consultant will subscribe on your behalf to the relevant topic(s).

You must provide an HTTPS server endpoint that will accept the event payload described below.

Your HTTPS server endpoint must accessible from the public web with a non-self-signed certificate.  The certificate should be signed by a known Certificate Authority and should be reachable through DNS.

Endpoint Requirements

The Event Subscription Service provides guaranteed at least once event delivery.  This is accomplished through retrying posting of the event payload to the subscribers' endpoint until the response indicates successful receipt.  The expected acknowledgment max for a request to the subscribers' endpoint is 30 seconds.  The service will attempt posting to the endpoint and then back-off and retry until the subscriber endpoint responds with delivered or not accepted.  SAP Concur suggests the subscriber endpoint implement the following behavior characteristics: * Ensure endpoint responds as quickly as possible (< 3 seconds) * The subscriber must maintain reasonable uptime to support the requirements of the integration scenario * If the subscriber must have durability of delivered events these must be persisted on the subscriber side * If the subscriber action on the event is non-idempotent or expensive guard against a duplicate event by checking the event Id has not already been processed.

Event Subscription Service (ESS) Behavior

The Event Subscription service has the following characteristics from the subscriber perspective:

Travel Search Event

Important: This API is currently in pre-release status and is only available to approved early access participants. The API is under development and might change before being generally released. To become an early access participant, contact your SAP Concur Representative.

Overview

The topic 'concur.travel.search' provides travel search information. Subscribers to this event will receive search criteria for travel searches performed within the SAP Concur online booking tool.

This event is relevant for applications that are interacting with travelers before they book their trip such as applications that context to the traveler regarding company policy, preferences, or general compliance requirements for booking travel.

Schema

Air

Name Type Format Description
id string GUID Uniquely identifies the event.
correlationId string GUID Uniquely identifies the air search request.
eventType string - Identifies the search event type. Supported values: travelSearchAir
topic string - Topic for subscription. Supported values: concur.travel.search
subTopic string - Identifies a sub topic. Supported values: airshop.v1.schedule, airshop.v1.price
timeStamp string date/time Search event time in UTC.
facts object Air Search Facts Facts for air search.

Air Search Facts

Name Type Format Description
companyId string GUID Uniquely identifies the company of the traveler.
userId string GUID Uniquely identifies the user performing the search. Note: In the event travel is booked by an arranger, this will be the traveler's ID. In cases where a profiled user is booking on behalf of a non profiled guest, this will be the user performing the search.
arrangerUserId string GUID If the user is also the traveler, this value will be the same as the userID above. If an arranger is booking on behalf of the traveler, this will uniquely identify the user arranging the trip.
searchLegs string - Type of air search. Supported values: RoundTrip, MultiSeg, OneWay
isGuestBooking boolean - Identifies if the booking is a guest.
isFlexFaring boolean - Identifies if search is for flex faring.
segments array Air Search Segment List of segments for search.
numberOfTravelers integer - Number of travelers.
classOfTrip string - Selected cabin class. Supported values: F = First Class, C = Business Class, W = Premium Economy, Y = Economy Class
airCarriers array - If the user filters for individual carriers, this list will be populated with the IATA airline carrier codes. Example: AA, VA, LH

Air Search Segment

Name Type Format Description
departures array City List of departure airports selected by the user. A user can select a city area/hub as point of departure, which will result in an array of multiple airports.
arrivals array City List of arrival airports selected by the user. A user can select a city area/hub as point of arrival, which will result in an array of multiple airports.
departureDate string YYYY-MM-DD Date traveler will depart from the point of departure, local time. Either the departure date/time, or the arrival date/time will be populated.
departureTime string HH:MM AM/PM Departure time, in local time. Either the departure date/time, or the arrival date/time will be populated.
departureTimeWindow integer - Time window (+/-) around selected departure time, in hours. Either the departure date/time, or the arrival date/time will be populated.
arrivalDate string YYYY-MM-DD Date on which the traveler will arrive at the destination, in local time. Either the departure date/time, or the arrival date/time will be populated.
arrivalTime string HH:MM AM/PM Time at which the traveler will arrive at the destination, in local time. Either the departure date/time, or the arrival date/time will be populated.
arrivalTimeWindow integer - Time window (+/-) around selected arrival time, in hours. Either the departure date/time, or the arrival date/time will be populated.

City

Name Type Format Description
cityName string - Name of the city. Example: Frankfurt
cityIATACode string - IATA code of the city. Example: FRA. Note: If the user searches for a group of airports (e.g. Los Angeles area airports), this code will not be IATA standard. In this case, the city name should be used.

Hotel

Name Type Format Description
id string GUID Uniquely identifies the event.
correlationId string GUID Uniquely identifies the hotel search request.
eventType string - Identifies the search event type. Supported values: travelSearchHotel
topic string - Topic for subscription. Supported values: concur.travel.search
subTopic string - Identifies sub-topic. Supported values: hotelshop.v1.price
timeStamp string date/time Search event time in UTC.
facts object Hotel Search Facts Facts for hotel search.

Hotel Search Facts

Name Type Format Description
companyId string GUID Uniquely identifies the company of the traveler.
userId string GUID Uniquely identifies the user performing the search. Note: In the event travel is booked by an arranger, this will be the traveler’s ID. In cases where a profiled user is booking on behalf of a non-profiled guest, this will be the user performing the search.
refPointLatitude number double Reference point for the search latitude.
refPointLongitude number double Reference point for the search longitude.
refPointName string - Reference point for the search name.
radiusDistance integer - Distance around the reference point as selected by the user.
distanceUnit string - Unit for radius distance. Supported values: Mile, Kilometer
checkInDate string YYYY-MM-DD Check in date, in local time.
checkOutDate string YYYY-MM-DD Check out date, in local time.

Sample Events

Air

Sample roundtrip air search

{
  "id": "00e4aeb3-d181-4881-89b1-0d0b5418968f",
  "correlationId": "51AB4E74-1287-4B20-87FB-98A93CE4CEEB",
  "eventType": "travelSearchAir",
  "topic": "concur.travel.search",
  "timeStamp": "2018-10-15T14:19:06.752Z",
  "data": null,
  "subtopic": null,
  "facts": {
    "companyId": "",
    "userId": "",
    "arrangerUserId": "",
    "searchLegs": "RoundTrip",
    "isGuestBooking": false,
    "isFlexFaring": false,
    "segments": [
    {
     "departures": [
          "LHR"
       ],
     "arrivals": [
          "FRA"
      ],
     "departureDate": "1/15/2019",
     "departureTime": "9:00 AM",
     "departureTimeWindow": 3,
     "arrivalDate": null,
     "arrivalTime": null,
     "arrivalTimeWindow": null
      },
     {
      "departures": [
          "FRA"
      ],
      "arrivals": [
         "LHR"
       ],
      "departureDate": "1/16/2019",
      "departureTime": "3:00 PM",
      "departureTimeWindow": 3,
      "arrivalDate": null,
      "arrivalTime": null,
      "arrivalTimeWindow": null
     }
    ],
  "numberOfTravelers": 1,
  "classOfTrip": null,
  "airCarriers": null
  }
}

Custom List Items

Custom list fields are included in many of the web services calls and they require some special consideration.

Value

When posting a list item, the list item code should be sent as the value, not the list item name. The code is returned in the levelxcode element of the Get List Items function.

Posting Connected List Items

There are two types of custom lists: Simple lists and Connected (multi-level) lists. If the list is a connected list, the list fields must be sent in sequential order, from parent to the lowest level child list item, as they are configured in the connected list definition.

Example: If your connected list uses Custom5 for the first level, Custom10 for the second level and Custom2 for the third level, you must send the XML elements for the custom fields in that order:

<Custom5>FirstValueCode</Custom5>  
<Custom10>SecondValueCode</Custom10>  
<Custom2>ThirdValueCode</Custom2>

Common Issues

Developers that post custom list item values can encounter errors when they post a list item that does not exist in the SAP Concur database. This can happen when the list item import hasn't been completed or hasn't run recently. If the posted list item code does not match an existing list item, the post may result in bad data. Use the List Item web service to ensure that the list items you are posting are present in the Concur database.

List Item v3

This API has been deprecated.

Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.

Learn more in the API Lifecycle & Deprecation Policy.

The SAP Concur List Item API provides an automated solution to clients who would like to add, update, or delete list items. Use of the API is subject to some limitations on the volume of List data. You may need to manage the initial load of large volumes of data via a file import due to capacity limitations. This is also true if ongoing maintenance of List values involves a large volume.

Version

3.0

1.0 documentation is available here

Retrieve All List Items Based on the Search Criteria

GET /api/v3.0/common/listitems

Parameters

Name Type Format Description
limit Int32 query The number of records to return. The default is 25 and the maximum is 100.
offset string query The start of the page offset. The default is from the beginning.
listId string query The unique identifier for the list this item is a member.
name string query The name of the listItem. Text Max length: 64.
parentId string query The unique identifier of this item's parent. Is empty when there is no parent.
level1Code string query The item code for the first level of the list. All lists have at least a Level1Code. Text maximum 32 characters
level2Code string query The item code for the second level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters
level3Code string query The item code for the third level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters
level4Code string query The item code for the fourth level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters
level5Code string query The item code for the fifth level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters
level6Code string query The item code for the sixth level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters
level7Code string query The item code for the seventh level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters
level8Code string query The item code for the eighth level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters
level9Code string query The item code for the ninth level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters
level10Code string query The item code for the tenth level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters

Retrieve a List Item by ID

GET /api/v3.0/common/listitems/{id}

Parameters

Name Type Format Description
id string path Required The unique identifier for the listItem.
listId string query The unique identifier for the list this item is a member.

Create a New List Item

POST /api/v3.0/common/listitems

Parameters

Name Type Format Description
content - body Required List item object to create.

Update a List Item

PUT /api/v3.0/common/listitems/{id}

Parameters

Name Type Format Description
id string path Required The unique identifier for the list item.
content - body Required The list item object to update.

Delete a List Item

DELETE /api/v3.0/common/listitems/{id}

Parameters

Name Type Format Description
id string path Required The unique identifier of the listitem to delete
listId string query Required The unique identifier of the list associated with a listitem to be deleted

Schema

List Items

Name Type Format Description
Items array List Item The result collection.
NextPage string - The URI of the next page of results, if any.

List Item

Name Type Format Description
ID string - The unique identifier of the resource.
Level10Code string - The item code for the tenth level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters
Level1Code string - The item code for the first level of the list. All lists have at least a Level1Code. Text maximum 32 characters
Level2Code string - The item code for the second level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters
Level3Code string - The item code for the third level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters
Level4Code string - The item code for the fourth level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters
Level5Code string - The item code for the fifth level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters
Level6Code string - The item code for the sixth level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters
Level7Code string - The item code for the seventh level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters
Level8Code string - The item code for the eighth level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters
Level9Code string - The item code for the ninth level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters
ListID string - The unique identifier for the list this item is a member.
Name string - The name of item. Text maximum 64 characters
ParentID string - The unique identifier of this item's parent. Is empty when there is no parent.
URI string - The URI to the resource.

List Item v4

The SAP Concur List Item API provides an automated solution to clients who would like to retrieve and add list items. Use of the API is subject to some limitations on the volume of list data. You may need to manage the initial load of large volumes of data via a file import due to capacity limitations. This is also true if ongoing maintenance of list values involves a large volume.

Limitations: This API is only available to partners who have been granted access by SAP Concur. Access to this documentation does not provide access to the API.

Contents

Prior Versions

Process Flow

A process flow diagram of the List Item API

Products and Editions

Scope Usage

Name Description Endpoint
spend.listitem.read Read-only access to spend list items. GET
spend.listitem.write Read and write access to spend list items. GET, POST, PUT
spend.listitem.delete Delete capabilities for spend list items. DELETE

Dependencies

Users must be an Expense, Invoice, Shared or Request Configuration Administrator in order to perform POST and PUT actions.

Access Token Usage

This API supports both company level and user level access tokens.

Retrieve a List Item by ID

Retrieve a list item by ID.

Scopes

spend.listitem.read - Refer to Scope Usage for full details.

Request

URI

Template
GET /list/v4/items/{itemId}
Parameters
Name Type Description
Accept-Language string Language code. Default: Company defined default language
itemId string Required The unique identifier of the list item.

Headers

Response

Status Codes

Headers

Payload

Example

Request

GET https://us.api.concursolutions.com/list/v4/items/{itemId}
Accept: application/json
Accept-Language: en
Authorization: Bearer {token}

Response

HTTP/1.1 200
concur-correlationid: 663d7795-fc21-4d98-ba31-87be20aeacd2
content-length: 360
content-type: application/json;charset=UTF-8
date: Wed, 08 Jul 2020 14:07:25 GMT
etag: "0950be10ca5a9f5069898e2468db6e137"
cache-control: no-cache, private
{
  "id": "63b7fbd9-ae08-0840-abdb-62b0b9160081",
  "code": "ITEM-SECOND LEVEL ITEM",
  "shortCode": "SECOND LEVEL ITEM",
  "value": "SECOND LEVEL ITEM",
  "parentId": "7c6d0435-c4d1-8b48-8492-7e7b625e148d",
  "level": 2,
  "isDeleted": false,
  "lists": [
    {
      "id": "80edb3fa-c15e-a34a-b97f-f2ec291ab44f",
      "hasChildren": false
    }
  ]
}

Create a List Item

Create a list item with the provided request body.

Scopes

spend.listitem.write - Refer to Scope Usage for full details.

Request

URI

Template
POST /list/v4/items
Parameters
Name Type Description
Accept-Language string Language code. Default: Company defined default language
listItem - Required List Item object that is created for the company.

Headers

Payload

Response

Status Codes

Headers

Payload

Example

Request

POST https://us.api.concursolutions.com/list/v4/lists
Accept: application/json
Accept-Language: en
Content-Type: application/json
Authorization: Bearer {token}

Example 1 (create first level list item): json { "listId": "80edb3fa-c15e-a34a-b97f-f2ec291ab44f", "shortCode": "ITEM", "value": "ITEM" }

Example 2 (create second level list item by parent list item ID): json { "listId": "80edb3fa-c15e-a34a-b97f-f2ec291ab44f", "parentId": "7c6d0435-c4d1-8b48-8492-7e7b625e148d", "shortCode": "SECOND LEVEL ITEM", "value": "SECOND LEVEL ITEM" }

Example 3 (create second level list item by parent list item code): json { "listId": "80edb3fa-c15e-a34a-b97f-f2ec291ab44f", "parentCode": "ITEM", "shortCode": "SECOND LEVEL ITEM", "value": "SECOND LEVEL ITEM" }

Response

HTTP/1.1 201
concur-correlationid: 85b8deb7-db84-4dfb-bdca-d4bccb2ef06e
content-length: 282
content-type: application/json;charset=UTF-8
date: Wed, 08 Jul 2020 13:47:25 GMT
location: http://localhost:5000/list/v4/items/7c6d0435-c4d1-8b48-8492-7e7b625e148d
cache-control: no-cache, private

Example 1: json { "id": "7c6d0435-c4d1-8b48-8492-7e7b625e148d", "code": "ITEM", "shortCode": "ITEM", "value": "ITEM", "parentId": null, "level": 1, "isDeleted": false, "lists": [ { "id": "80edb3fa-c15e-a34a-b97f-f2ec291ab44f", "hasChildren": false } ] } Example 2 and Example 3: json { "id": "63b7fbd9-ae08-0840-abdb-62b0b9160081", "code": "ITEM-SECOND LEVEL ITEM", "shortCode": "SECOND LEVEL ITEM", "value": "SECOND LEVEL ITEM", "parentId": "7c6d0435-c4d1-8b48-8492-7e7b625e148d", "level": 2, "isDeleted": false, "lists": [ { "id": "80edb3fa-c15e-a34a-b97f-f2ec291ab44f", "hasChildren": false } ] }

Update a List Item

Update a list item with provided request body.

Scopes

spend.listitem.write - Refer to Scope Usage for full details.

Request

URI

Template
PUT /list/v4/items/{itemId}
Parameters
Name Type Description
Accept-Language string Language code. Default: Company defined default language
itemId string Required The unique identifier of the list item.
listItem - Required List Item object that is updated.

Headers

Payload

Response

Status Codes

Headers

Payload

Example

Request

PUT https://us.api.concursolutions.com/list/v4/items/7c6d0435-c4d1-8b48-8492-7e7b625e148d
Accept: application/json
Accept-Language: en
Content-Type: application/json
Authorization: Bearer {token}
{
  "shortCode": "ITEM",
  "value": "ITEM UPDATED"
}

Response

HTTP/1.1 200
concur-correlationid: 27abed5d-20cc-4edf-81b6-3e2dbf70ba39
content-length: 289
content-type: application/json;charset=UTF-8
date: Wed, 08 Jul 2020 14:16:21 GMT
cache-control: no-cache, private
{
  "id": "7c6d0435-c4d1-8b48-8492-7e7b625e148d",
  "code": "ITEM",
  "shortCode": "ITEM",
  "value": "ITEM UPDATED",
  "parentId": null,
  "level": 1,
  "isDeleted": false,
  "lists": [
    {
      "id": "80edb3fa-c15e-a34a-b97f-f2ec291ab44f",
      "hasChildren": true
    }
  ]
}

Delete a List Item

Delete a list item by list item ID. A list item shared between multiple lists will be deleted from all lists.

Scopes

spend.listitem.delete - Refer to Scope Usage for full details.

Request

URI

Template
DELETE /list/v4/items/{itemId}
Parameters
Name Type Description
itemId string Required The unique identifier of the list item.

Headers

Response

Status Codes

Headers

Payload

Example

Request

DELETE https://us.api.concursolutions.com/list/v4/items/7c6d0435-c4d1-8b48-8492-7e7b625e148d
Accept: application/json
Authorization: Bearer {token}

Response

HTTP/1.1 204
concur-correlationid: d92ab0c7-510b-4730-99a8-14a79ad99b7c
date: Wed, 08 Jul 2020 14:16:21 GMT
cache-control: no-cache, private

Delete a List Item from a List

Delete a list item by list item ID from a particular list. This enables deleting a shared list item from one list, not all lists.

Scopes

spend.listitem.delete - Refer to Scope Usage for full details.

Request

URI

Template
DELETE /list/v4/lists/{listId}/items/{itemId}
Parameters
Name Type Description
listId string Required The unique identifier of the list.
itemId string Required The unique identifier of the list item.

Headers

Response

Status Codes

Headers

Payload

Example

Request

DELETE https://us.api.concursolutions.com/list/v4/lists/80edb3fa-c15e-a34a-b97f-f2ec291ab44f/items/7c6d0435-c4d1-8b48-8492-7e7b625e148d
Accept: application/json
Authorization: Bearer {token}

Response

HTTP/1.1 204
concur-correlationid: d92ab0c7-510b-4730-99a8-14a79ad99b7c
date: Wed, 08 Jul 2020 14:16:21 GMT
cache-control: no-cache, private

Retrieve Children of a List Item

Retrieve the direct children for a given list item.

Scopes

spend.listitem.read - Refer to Scope Usage for full details.

Request

URI

Template
GET /list/v4/items/{itemId}/children?page={page}&sortBy={sortBy}
Parameters
Name Type Description
Accept-Language string Language code. Default: Company defined default language
hasChildren boolean If true, displays items with children.
isDeleted boolean If true, displays deleted items.
itemId string Required The unique identifier of the list item.
page integer Page number starting from 1. Default: 1
shortCode string Filter capabilities for shortCode.
shortCodeOrValue string Filter capabilities for value or shortCode.
sortBy string Field to sort by. Supported values: value, shortCode. Default: value
sortDirection string Sort direction. Supported values: asc, desc
value string Filter capabilities for value.

Headers

Response

Status Codes

Headers

Payload

Example

Request

GET https://us.api.concursolutions.com/list/v4/items/7c6d0435-c4d1-8b48-8492-7e7b625e148d/children?page=1&sortBy=value
Accept: application/json
Accept-Language: en
Authorization: Bearer {token}

Response

HTTP/1.1 200
concur-correlationid: 50dcec14-c984-479c-84e2-186a7e62f87e
content-length: 449
content-type: application/json;charset=UTF-8
date: Wed, 08 Jul 2020 14:27:13 GMT
etag: "05cb0f0ed5a73bedf1e8cd4171e360e41"
cache-control: no-cache, private
{
  "links": [],
  "content": [
    {
      "id": "63b7fbd9-ae08-0840-abdb-62b0b9160081",
      "code": "ITEM-SECOND LEVEL ITEM",
      "shortCode": "SECOND LEVEL ITEM",
      "value": "SECOND LEVEL ITEM",
      "parentId": "7c6d0435-c4d1-8b48-8492-7e7b625e148d",
      "level": 2,
      "isDeleted": false,
      "lists": [
        {
          "id": "80edb3fa-c15e-a34a-b97f-f2ec291ab44f",
          "hasChildren": false
        }
      ]
    }
  ],
  "page": {
    "size": 100,
    "totalElements": 1,
    "totalPages": 1,
    "number": 1
  }
}

Retrieve Children of a List Item by List

Retrieve the direct children for a given list item in a particular list. For a list item shared between multiple lists, this API enables retrieving children from a particular list.

Scopes

spend.listitem.read - Refer to Scope Usage for full details.

Request

URI

Template
GET /list/v4/lists/{listId}/items/{itemId}/children?page={page}&sortBy={sortBy}
Parameters
Name Type Description
Accept-Language string Language code. Default: Company defined default language
hasChildren boolean If true, displays items with children.
isDeleted boolean If true, displays deleted items.
itemId string Required The unique identifier of the list item.
listId string Required The unique identifier of the list.
page integer Page number starting from 1. Default: 1
shortCode string Filter capabilities for shortCode.
shortCodeOrValue string Filter capabilities for value or shortCode.
sortBy string Field to sort by. Supported values: value, shortCode. Default: value
sortDirection string Sort direction. Supported values: asc, desc
value string Filter capabilities for value.

Headers

Response

Status Codes

Headers

Payload

Example

Request

GET https://us.api.concursolutions.com/list/v4/lists/80edb3fa-c15e-a34a-b97f-f2ec291ab44f/items/7c6d0435-c4d1-8b48-8492-7e7b625e148d/children?page=1&sortBy=value
Accept: application/json
Accept-Language: en
Authorization: Bearer {token}

Response

HTTP/1.1 200
concur-correlationid: 50dcec14-c984-479c-84e2-186a7e62f87e
content-length: 449
content-type: application/json;charset=UTF-8
date: Wed, 08 Jul 2020 14:27:13 GMT
etag: "05cb0f0ed5a73bedf1e8cd4171e360e41"
cache-control: no-cache, private
{
  "links": [],
  "content": [
    {
      "id": "63b7fbd9-ae08-0840-abdb-62b0b9160081",
      "code": "ITEM-SECOND LEVEL ITEM",
      "shortCode": "SECOND LEVEL ITEM",
      "value": "SECOND LEVEL ITEM",
      "parentId": "7c6d0435-c4d1-8b48-8492-7e7b625e148d",
      "level": 2,
      "isDeleted": false,
      "lists": [
        {
          "id": "80edb3fa-c15e-a34a-b97f-f2ec291ab44f",
          "hasChildren": false
        }
      ]
    }
  ],
  "page": {
    "size": 100,
    "totalElements": 1,
    "totalPages": 1,
    "number": 1
  }
}

Retrieve First Level Children Items of a List

Retrieves the first level list items for a given List ID.

Scopes

spend.listitem.read - Refer to Scope Usage for full details.

Request

URI

Template
GET /list/v4/lists/{listId}/children?page={page}&sortBy={sortBy}
Parameters
Name Type Description
Accept-Language string Language code. Default: Company defined default language
hasChildren boolean If true, displays items with children.
isDeleted boolean If true, displays deleted items.
listId string Required The unique identifier of the list.
page integer Page number starting from 1. Default: 1
shortCode string Filter capabilities for shortCode.
shortCodeOrValue string Filter capabilities for value or shortCode.
sortBy string Field to sort by. Supported values: value, shortCode. Default: value
sortDirection string Sort direction. Supported values: asc, desc
value string Filter capabilities for value.

Headers

Response

Status Codes

Headers

Payload

Example

Request

GET https://us.api.concursolutions.com/list/v4/lists/7c6d0435-c4d1-8b48-8492-7e7b625e148d/children?page=1&sortBy=value
Accept: application/json
Accept-Language: en
Authorization: Bearer {token}

Response

HTTP/1.1 200
concur-correlationid: 50dcec14-c984-479c-84e2-186a7e62f87e
content-length: 449
content-type: application/json;charset=UTF-8
date: Wed, 08 Jul 2020 14:27:13 GMT
etag: "05cb0f0ed5a73bedf1e8cd4171e360e41"
cache-control: no-cache, private
{
  "links": [],
  "content": [
    {
      "id": "63b7fbd9-ae08-0840-abdb-62b0b9160081",
      "code": "ITEM-FIRST LEVEL ITEM",
      "shortCode": "FIRST LEVEL ITEM",
      "value": "FIRST LEVEL ITEM",
      "level": 1,
      "isDeleted": false,
      "lists": [
        {
          "id": "7c6d0435-c4d1-8b48-8492-7e7b625e148d",
          "hasChildren": false
        }
      ]
    }
  ],
  "page": {
    "size": 100,
    "totalElements": 1,
    "totalPages": 1,
    "number": 1
  }
}

Filtering

Supported APIs

The List Item API supports filtering on the Retrieve First Level Children Items of a List, Retrieve Children of a List Item, and Retrieve Children of a List Item by List APIs. The filter may be applied to the value, shortCode, and shortCodeOrValue query parameters.

Retrieve First Level Children Items of a List
GET /lists/v4/lists/{listId}/children?value=test
GET /lists/v4/lists/{listId}/children?shortCode=test
GET /lists/v4/lists/{listId}/children?shortCodeOrValue=test
Retrieve Children of a List Item
GET /lists/v4/items/{listId}/children?value=test
GET /lists/v4/items/{listId}/children?shortCode=test
GET /lists/v4/items/{listId}/children?shortCodeOrValue=test
Retrieve Children of a List Item by List
GET /list/v4/lists/{listId}/items/{itemId}/children?value=test
GET /list/v4/lists/{listId}/items/{itemId}/children?shortCode=test
GET /list/v4/lists/{listId}/items/{itemId}/children?shortCodeOrValue=test

Query Syntax

The general format of a query syntax parameter is as follows:

/lists/v4/resource?field_name=<op>:<value>

Ensure the url generated is properly URL encoded. For example, if you have a field_name or value with a &, please convert it to %26.

Examples:

/lists/v4/lists/{listId}/children?value=PSO
/lists/v4/lists/{listId}/children?shortCode=sw:British
/lists/v4/lists/{listId}/children?value=ew:Airlines&shortCode=not:British+Airlines
/lists/v4/lists/{listId}/children?value=sw:Question%3FMark

Conjunction Operators

Complex queries using parentheses are not supported.

There is basic support for OR functionality with the shortCodeOrValue query parameter. shortCodeOrValue will search both shortCode and value properties and return all resources that match either field.

Comparison Operators

Equals

eq returns results where a field is equal to the supplied value. This is the default if no operator is specified.

/lists/v4/lists/{listId}/children?value=test
/lists/v4/items/{itemId}/children?value=eq:test
/lists/v4/items/{itemId}/children?shortCodeOrValue=eq:test

Contains Pattern

cp returns results where the provided pattern exists in the specified field.

/lists/v4/lists/{listId}/children?value=cp:test

Not

not returns results where a field is not equal to the supplied value.

/lists/v4/items/{itemId}/children?shortCode=not:test

Starts With

sw returns results where a field startsWith the supplied value.

/lists/v4/lists/{listId}/children?shortCode=sw:test

Ends With

ew returns results where a field endsWith the supplied value.

/lists/v4/items/{itemId}/children?value=ew:test

Schema

List Item

Name Type Format Description
id string uuid The unique identifier of the list item.
code string - List item long code.
shortCode string - List item short code.
value string - List item value.
parentId string uuid The unique identifier of the parent list item.
listId string uuid The unique identifier of the list that contains the list item.
level integer int32 Level of the list item within the list.
lists ListItemMemberList - The unique identifiers of the lists that contains the list item. The list item may exist under one or more lists.
isDeleted boolean true/false Indicates the deleted state of the item in a particular list. If false, the list item is not deleted from one or more lists. The lists field will include only the lists that contain the list item in a not-deleted state. isDeleted will only be true when the list item is deleted from all lists. The lists field will include all lists that contain the list item.

List Item Create

Name Type Format Description
listId string uuid Required The unique identifier of the list that contains the list item.
parentCode string - The long code of parent list item.
parentId string uuid The unique identifier of parent list item.
shortCode string - Required List item short code.
value string - Required List item value.

List Item Update

Name Type Format Description
shortCode string - Required List item short code.
value string - Required List item value.

List Item Member List

Name Type Format Description
id string uuid The unique identifier of the list that contains the list item.
hasChildren boolean true/false If true, the list item has children in this particular list.

Paged Resources List Item

Name Type Format Description
content array ListItem -
page PageMetadata - Metadata for the page of data returned
links array Link Href links to the next, previous, first, and/or last pages of data.

Error Message

Name Type Format Description
error Message - Required The detailed error message.
httpStatus string - Required The http response code and phrase for the response.
path string - Required The URI of the attempted request.
timestamp string date-time Required The time when the error was captured.
validationErrors array ValidationError The validation error messages.

Validation Error

Name Type Format Description
message string - The detailed message of the validation error.
source string - The type of validation that failed.

Message

Name Type Format Description
message string - The detailed error message.
id string - The identifier of the error.

Page Metadata

Name Type Format Description
number integer int32 The page number.
size integer int32 The number of items per page, which is fixed at 100.
totalElements integer int32 The number of total elements.
totalPages integer int32 The number of total pages.
Name Type Format Description
rel string - The link relation.
href string - The link href.

Lists v3

This API has been deprecated.

Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.

Learn more in the API Lifecycle & Deprecation Policy.

The Lists API allows you to view your configured lists within SAP Concur products, and create new lists. The lists are shared between multiple SAP Concur products. Use the List Items API to manage the items in the lists.

Products and Editions

Scope Usage

Name Description Endpoint
LIST Use and update lists configured by your company. GET, POST

Get All Lists

Returns all lists based on the search criteria.

Parameters

Name Type Format Description
limit integer The default is 25 and the maximum is 100. Optional. The number of records to return.
offset string - Optional. The start of the page offset. The default is from the beginning.

Request

GET https://www.concursolutions.com/api/v3.0/common/lists HTTP/1.1
Host: www.concursolutions.com
Accept: application/json
 const headers = {
  'Accept':'application/json'

};

fetch('https://www.concursolutions.com/api/v3.0/common/lists',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

Response

200 Response

{
  "Items": {
    "ConnectorID": "string",
    "DisplayCodeFirst": true,
    "ExternalThreshold": 0,
    "ID": "string",
    "IsVendorList": true,
    "Name": "string",
    "SearchCriteriaCode": "string",
    "URI": "string"
  },
  "NextPage": "string"
}

Create a New List

Creates a new list.

Parameters

Name Type Format Description
content ListPost - Required. List object to create.

Request

POST https://www.concursolutions.com/api/v3.0/common/lists HTTP/1.1
Host: www.concursolutions.com
Content-Type: application/json
Accept: application/json
const inputBody = '{
  "ConnectorID": "string",
  "DisplayCodeFirst": true,
  "ExternalThreshold": 0,
  "IsVendorList": true,
  "Name": "string",
  "SearchCriteriaCode": "string"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json'

};

fetch('https://www.concursolutions.com/api/v3.0/common/lists',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

Response

200 Response

{
  "ID": "string",
  "URI": "string"
}

Get a Single List by ID

Returns a list by ID.

Parameters

Name Type Format Description
id string - Required.The unique identifier for the list.

Request

GET https://www.concursolutions.com/api/v3.0/common/lists/{id} HTTP/1.1
Host: www.concursolutions.com
Accept: application/json


const headers = {
  'Accept':'application/json'

};

fetch('https://www.concursolutions.com/api/v3.0/common/lists/{id}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

Response

200 Response

{
  "ConnectorID": "string",
  "DisplayCodeFirst": true,
  "ExternalThreshold": 0,
  "ID": "string",
  "IsVendorList": true,
  "Name": "string",
  "SearchCriteriaCode": "string",
  "URI": "string"
}

Update List

DEPRECATED: 05/19/2016 UNSUPPORTED: 11/19/2016. Updates list specified in the URL. Only the fields provided in the supplied object will be updated, missing fields will not be altered.

Parameters

Name Type Format Description
id string - Required. The unique identifier for the list.
content ListPut - Required. The list object to update.

Request

PUT https://www.concursolutions.com/api/v3.0/common/lists/{id} HTTP/1.1
Host: www.concursolutions.com
Content-Type: application/json
Accept: application/json

const inputBody = '{
  "DisplayCodeFirst": true,
  "Name": "string",
  "SearchCriteriaCode": "string"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json'

};

fetch('https://www.concursolutions.com/api/v3.0/common/lists/{id}',
{
  method: 'PUT',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

Schema

CreateResponse

Name Type Format Description
ID string -
URI string -

ListGet

Name Type Format Description
ConnectorID string - Optional. Defines the encrypted ConnectorID. If not provided then the list isn't associated with a connector.
DisplayCodeFirst Boolean - Required. Defines whether code should appear before text, or vice versa.
ExternalThreshold integer - Optional. Default value is 1. Defines the threshold from where the level starts being external. This value can only be set if a ConnectorID is provided.
ID string - The unique identifier of the resource.
IsVendorList Boolean - Required. Defines whether it is a vendor list.
Name string - Required. Defines a name for the list. This name must be unique.
SearchCriteriaCode string - Required. Defines whether the search criteria should apply to the code or to the text.
URI string - The URI to the resource.

ListGetCollection

Name Type Format Description
Items ListGet -
NextPage string - The URI of the next page of results, if any.

ListPost

Name Type Format Description
ConnectorID string - Optional. Defines the encrypted ConnectorID. If not provided then the list isn't associated with a connector.
DisplayCodeFirst Boolean - Required. Defines whether code should appear before text, or vice versa.
ExternalThreshold integer - Optional. Default value is 1. Defines the threshold from where the level starts being external. This value can only be set if a ConnectorID is provided.
IsVendorList Boolean - Required. Defines whether it is a vendor list.
Name string - Required. Defines a name for the list. This name must be unique.
SearchCriteriaCode string - Required. Defines whether the search criteria should apply to the code or to the text.

ListPut

Name Type Format Description
DisplayCodeFirst Boolean - Optional. Defines whether code should appear before text, or vice versa.
Name string - Optional. Defines a name for the list. This name must be unique.
SearchCriteriaCode string - Optional. Defines whether the search criteria should apply to the code or to the text.

List v4

The Lists APIs allow you to view your configured lists within SAP Concur products and create new lists. The lists are shared between multiple SAP Concur products.

Limitations: This API is only available to partners who have been granted access by SAP Concur. Access to this documentation does not provide access to the API.

Contents

Prior Versions

List v3 documentation is available here.

Process Flow

A process flow diagram of the List API

Products and Editions

Scope Usage

Name Description Endpoints
spend.list.read Read-only access to spend lists. GET
spend.list.write Read and write access to spend lists. GET, POST, PUT
spend.list.delete Delete capabilities for spend lists. DELETE

Dependencies

Users must be an Expense, Invoice, Shared or Request Configuration Administrator in order to perform POST, PUT, and DELETE actions.

Access Token Usage

This API supports both company level and user level access tokens.

Get All Lists

Returns all lists for a company.

Scopes

spend.list.read - Refer to Scope Usage for full details.

Request

URI

Template
GET /list/v4/lists
Parameters
Name Type Description
Accept-Language string Language code. Default: Company defined default language
page integer($int32) Page number starting from 1. Default: 1
sortBy string Field to order by {name, levelcount, listcategory}. Sort by name is ordered by value. Sort by levelcount is ordered by levelCount. Sort by listcategory is ordered by category.type. Default: name
sortDirection string Sort direction {asc, desc}. Default: asc

Headers

Response

Status Codes

Headers

Payload

Example

Request

GET https://us.api.concursolutions.com/list/v4/lists?page=1
Accept: application/json
Accept-Language: en
Authorization: Bearer {token}

Response

HTTP/1.1 200
concur-correlationid: 746696dc-8782-4642-815d-3080640786c7
content-length: 5632
content-type: application/json;charset=UTF-8
date: Wed, 08 Jul 2020 02:45:48 GMT
etag: "02ebe9fc5c950a031f85c57ac91a0babb"
cache-control: no-cache, private
{
    "links": [],
    "content": [
        {
            "id": "a80a5070-3951-4316-886a-a60ab790f06b",
            "value": "Airlines",
            "levelCount": 1,
            "searchCriteria": "TEXT",
            "displayFormat": "(CODE) TEXT",
            "category": {
                "id": "a2dfc451-8f3c-410e-a5f2-20d79c8fc3dc",
                "type": "Vendor"
            },
            "isReadOnly": false,
            "isDeleted": false
        },
        {
            "id": "8652cdf9-c12b-4051-b8d1-80e20840ce9b",
            "value": "Employee Groups",
            "levelCount": 1,
            "searchCriteria": "TEXT",
            "displayFormat": "(CODE) TEXT",
            "category": {
                "id": "d232b1e3-43da-4a2d-adaf-eb948045e8cf",
                "type": "Configuration"
            },
            "isReadOnly": false,
            "isDeleted": false
        }
    ],
    "page": {
        "size": 100,
        "totalElements": 2,
        "totalPages": 1,
        "number": 1
    }
}

Create a New List

Creates a new list.

Scopes

spend.list.write - Refer to Scope Usage for full details.

Request

URI

Template
POST /list/v4/lists
Parameters
Name Type Description
Accept-Language string Language code. Default: Company defined default language
listRequest - Required List object that is created for the company.

Headers

Payload

Response

Status Codes

Headers

Payload

Example

Request

POST https://us.api.concursolutions.com/list/v4/lists
Accept: application/json
Content-Type: application/json
Authorization: Bearer {token}
Example 1:
{
  "searchCriteria": "TEXT",
  "value": "Custom List",
  "displayFormat": "(CODE) TEXT"
}
Example 2:
{
  "searchCriteria": "TEXT",
  "value": "Custom Vendor List",
  "categoryId": "a2dfc451-8f3c-410e-a5f2-20d79c8fc3dc",
  "displayFormat": "(CODE) TEXT"
}

Response

HTTP/1.1 201
concur-correlationid: 5512c7be-3fab-4d65-ae69-8a74a04a0c7f
content-length: 269
content-type: application/json;charset=UTF-8
date: Wed, 08 Jul 2020 03:00:42 GMT
location: http://us.api.concursolutions.com/list/v4/lists/80edb3fa-c15e-a34a-b97f-f2ec291ab44f
cache-control: no-cache, private
{
    "id": "80edb3fa-c15e-a34a-b97f-f2ec291ab44f",
    "value": "Custom List",
    "levelCount": 1,
    "searchCriteria": "TEXT",
    "displayFormat": "(CODE) TEXT",
    "category": {
        "id": "77b85a76-8157-0c4e-b5e3-7785d8de1a6b",
        "type": "Normal"
    },
    "isReadOnly": false,
    "isDeleted": false
}

Update a List

Update an existing list.

Scopes

spend.list.write - Refer to Scope Usage for full details.

Request

URI

Template
PUT /list/v4/lists/{listId}
Parameters
Name Type Description
Accept-Language string Language code. Default: Company defined default language
listId string($uuid) Required The unique identifier of the list.
listUpdate - Required List object that is updated for the company.

Headers

Payload

Response

Status Codes

Headers

Payload

Example

Request

PUT https://us.api.concursolutions.com/list/v4/lists/80edb3fa-c15e-a34a-b97f-f2ec291ab44f
Accept: application/json
Accept-Language: en
Content-Type: application/json
Authorization: Bearer {token}
{
  "value": "Custom List Renamed",
  "searchCriteria": "TEXT",
  "displayFormat": "(CODE) TEXT"
}

Response

HTTP/1.1 200
concur-correlationid: e3a4d4cf-e1b2-4f22-a95c-b5bb8a2cb0e1
content-length: 275
content-type: application/json;charset=UTF-8
date: Wed, 08 Jul 2020 03:24:16 GMT
cache-control: no-cache, private
{
  "id": "80edb3fa-c15e-a34a-b97f-f2ec291ab44f",
  "value": "Custom List Renamed",
  "levelCount": 1,
  "searchCriteria": "TEXT",
  "displayFormat": "(CODE) TEXT",
  "category": {
    "id": "77b85a76-8157-0c4e-b5e3-7785d8de1a6b",
    "type": "Normal"
  },
  "isReadOnly": false,
  "isDeleted": false
}

Get a List by List ID

Returns a list by a List ID.

Scopes

spend.list.read - Refer to Scope Usage for full details.

Request

URI

Template
GET /list/v4/lists/{listId}
Parameters
Name Type Description
Accept-Language string Language code. Default: Company defined default language
listId string($uuid) Required The unique identifier of the list.

Headers

Response

Status Codes

Headers

Payload

Example

Request

GET https://us.api.concursolutions.com/list/v4/lists/80edb3fa-c15e-a34a-b97f-f2ec291ab44f
Accept: application/json
Accept-Language: en
Authorization: Bearer {token}

Response

HTTP/1.1 200
concur-correlationid: 6a5803f6-b63b-49d8-88b3-872f456206c2
content-length: 275
content-type: application/json;charset=UTF-8
date: Wed, 08 Jul 2020 02:45:48 GMT
etag: "08514b0fce90d634c211aba29d1cc94c2"
cache-control: no-cache, private
{
  "id": "80edb3fa-c15e-a34a-b97f-f2ec291ab44f",
  "value": "Custom List Renamed",
  "levelCount": 1,
  "searchCriteria": "TEXT",
  "displayFormat": "(CODE) TEXT",
  "category": {
    "id": "77b85a76-8157-0c4e-b5e3-7785d8de1a6b",
    "type": "Normal"
  },
  "isReadOnly": false,
  "isDeleted": false
}

Get a List by Category ID

Returns a list by a category ID.

Scopes

spend.list.read - Refer to Scope Usage for full details.

Request

URI

Template
GET /list/v4/categories/{categoryId}/lists
Parameters
Name Type Description
Accept-Language string Language code. Default: Company defined default language
categoryId string($uuid) Required The unique identifier of the category.
page integer($int32) Page number starting from 1. Default: 1

Headers

Response

Status Codes

Headers

Payload

Example

Request

GET https://us.api.concursolutions.com/list/v4/categories/77b85a76-8157-0c4e-b5e3-7785d8de1a6b/lists?page=1
Accept: application/json
Accept-Language: en
Authorization: Bearer {token}

Response

HTTP/1.1 200
concur-correlationid: 0e80dff7-93b7-4b43-a1b6-a91ebe5c55f0
content-length: 364
content-type: application/json;charset=UTF-8
date: Wed, 08 Jul 2020 02:45:48 GMT
etag: "02e60234cf6ae61aadd7f066e839b07fb"
cache-control: no-cache, private
{
  "links": [],
  "content": [
    {
      "id": "80edb3fa-c15e-a34a-b97f-f2ec291ab44f",
      "value": "Custom List Renamed",
      "levelCount": 1,
      "searchCriteria": "TEXT",
      "displayFormat": "(CODE) TEXT",
      "category": {
        "id": "77b85a76-8157-0c4e-b5e3-7785d8de1a6b",
        "type": "Normal"
      },
      "isReadOnly": false,
      "isDeleted": false
    }
  ],
  "page": {
    "size": 100,
    "totalElements": 1,
    "totalPages": 1,
    "number": 1
  }
}

Remove a List

Delete a list.

Scopes

spend.list.delete - Refer to Scope Usage for full details.

Request

URI

Template
DELETE /list/v4/lists/{listId}
Parameters
Name Type Description
listId string($uuid) Required The unique identifier of the list.

Headers

Response

Status Codes

Headers

Payload

Example

Request

DELETE https://us.api.concursolutions.com/list/v4/lists/80edb3fa-c15e-a34a-b97f-f2ec291ab44f
Accept: application/json
Authorization: Bearer {token}

Response

HTTP/1.1 204
concur-correlationid: d92ab0c7-510b-4730-99a8-14a79ad99b7c
date: Wed, 08 Jul 2020 02:45:48 GMT
cache-control: no-cache, private

Schema

Paged Resources List Response

Name Type Format Description
content array ListResponse -
page PageMetadata - Metadata for the page of data returned.
links array Link Href links to the next, previous, first, and/or last pages of data.

List Response

Name Type Format Description
id string uuid Unique identifier of a list.
value string - Name of the list.
levelCount integer int32 Number of levels in the list.
searchCriteria string - What attribute to search by {TEXT, CODE}.
displayFormat string - Whether the code or value is displayed first {(CODE) TEXT, TEXT (CODE)}.
category ListCategory - The category of the list.
isReadOnly boolean true/false If true, the list is read-only.
isDeleted boolean true/false If true, the list has been deleted.

List Category

Name Type Format Description
id string uuid Unique identifier of a category.
type string - Category type.

List Request

Name Type Format Description
searchCriteria string - What attribute to search by. Supported values: TEXT, CODE
value string - Required Name of the list.
categoryId string uuid The unique identifier of the category that the list belongs to.
displayFormat string - Whether we display code or value first. Supported values: (CODE) TEXT, TEXT (CODE)

List Update

Name Type Format Description
value string - Required Name of the list.
searchCriteria string - What attribute to search by. Supported values: TEXT, CODE
displayFormat string - Whether we display code or value first. Supported values: (CODE) TEXT, TEXT (CODE)

Message

Name Type Format Description
message string - The detailed error message.
id string - The identifier of the error.

Page Metadata

Name Type Format Description
number integer int32 The page number.
size integer int32 The number of lists per page, which is fixed at 100.
totalElements integer int32 The number of total elements.
totalPages integer int32 The number of total pages.
Name Type Format Description
rel string - The link relation.
href string - The link href.

Error Message

Name Type Format Description
error Message - Required The detailed error message.
httpStatus string - Required The http response code and phrase for the response.
path string - Required The URI of the attempted request.
timestamp string date-time Required The time when the error was captured.
validationErrors array ValidationError The validation error messages.

Validation Error

Name Type Format Description
message string - The detailed message of the validation error.
source string - The type of validation that failed.

Locations v3

Gets details of locations that are used by Concur and that are valid at the user's company.

Location v1.1 has been deprecated and can be found here.

Retrieve details of locations that are used by Concur and that are valid at the user's company

GET /api/v3.0/common/locations

Parameters

Name Type Format Description
offset string query The starting point of the next set of results, after the limit specified in the limit field has been reached.
limit Int32 query The number of records to return. Default value: 25
name string query A common name associated with the location. This name can be a location description such as a neighborhood (SoHo), a landmark (Statue of Liberty), or a city name (New York).
city string query The city name of the location.
countrySubdivision string query The ISO 3166-2:2007 country subdivision code for the location. Example: US-WA
country string query The 2-letter ISO 3166-1 country code for the location. Example: United States is US
administrativeRegion string query The administrative region of the location. An administrative region is a government unit, such as a county, that contains one or more cities.

Retrieve details of a specified location

GET /api/v3.0/common/locations/{id}

Parameters

Name Type Format Description
id string path Required The ID of the location.

Schema

Locations

Name Type Format Description
Items Array Location The result collection.
NextPage string - The URI of the next page of results, if any.

Location

Name Type Format Description
AdministrativeRegion string - The administrative region of the location.
Country string - The 2-letter ISO 3166-1 country code for the location.
CountrySubdivision string - The ISO 3166-2:2007 country subdivision code for the location. Example: US-WA
IATACode string - The International Air Transport Association (IATA) airport code of the location.
ID string - The unique identifier of the resource.
IsAirport boolean - Indicates whether the location is an airport. Format: true or false
IsBookingTool boolean - Indicates whether the location is used by the booking tool. Format: true or false
Latitude Decimal - The latitude of the geocode for the location.
Longitude Decimal - The longitude of the geocode for the location.
Name string - The location name. Maximum length: 64 characters
URI string - The URI to the resource.

Suppliers v3

Suppliers

Supplier companies provide travel services to users. The Suppliers resource can be used to retrieve information about suppliers.

Retrieve all suppliers based on search criteria

GET /api/v3.0/common/suppliers/

Parameters

Name Type Format Description
name query string Name
address query string Address
address2 query string Address
city query string City
state query string State
zip query string Zip
country query string Country Code
phone query string Phone
mcCode query string MCC Code (Ex: Delta Airline - 3058)
taxId query string Tax Id
merchantType query string Merchant Type Code(Ex: Visa - VI, Amex - AX)
merchantID query string Merchant Id
iataCode query string IATA Code
relevance query Int32 Relevance of the Search results5

Retrieve a single supplier by ID

GET /api/v3.0/common/suppliers/{id}

Parameters

Name Type Format Description
id string path Required Supplier ID.

Schema

Suppliers

Name Type Format Description
Items Array Supplier The result connection
NextPage string - The URI of the next page of results, if any.

Supplier

Name Type Format Description
AmadeusId string - Amadeus Id
AustinTetra string - Austin Tetra
BusinessName string - Name
ChainCode string - Chain Code
ChainName string - Chain Name
City string - City
CountryCode string - Country Code
CreditCardVendorId string - Creditcard Vendor Id
DunsNumber string - Duns Number
Email string - Email
Fax string - Fax
GalileoId string - Galileo Id
ID string - The unique identifier of the resource.
MccCode string - MCC Code (Ex: Delta Airline - 3058)
NorthstarId string - Northstar Id
PegasusId string - Pegasus Id
Phone string - Phone
PostalCode string - Zip
PrimaryNaics string - Primary Naics Code
PrimarySic string - Primary Sic Code
PropertyCode string - SUP_PARAM_PROPERTY_CODE
SabreId string - Sabre Id
SecondaryNaics string - Secondary Naics Code
SecondarySic string - Secondary Sic Code
State string - State
StreetAddress string - Address
StreetAddress2 string - Address2
TaxId string - Tax Id
TollFree string - Toll Free
URI string - The URI to the resource.
WebUrl string - Web Address
WorldspanId string - Worldspan Id

DETOKENIZER

Detokenizer v4

Important: This API is currently in pre-release status and is only available to approved early access participants. The API is under development and might change before being generally released. To become an early access participant, contact your SAP Concur Representative.

The Detokenizer service allows clients to retrieve the user's credit card number from Concur Expense in a secure way. The Detokenizer service returns the user's credit card number encrypted with a public key that the client provides in the request. The client will be able to decrypt the user's credit card number using their private key.

Limitations: This API is only for internal use to support various SAP integration features or to the SAP Concur customer that has established corporate credit card accounts involved in the data (the “Customer Corporate Card Holder”). Such use must be in compliance with regulations and other industry standards, including but not limited to Payment Card Industry Data Security Standards (PCI DSS). If you are a Customer Corporate Card Holder that desires to use this API, you must work with your account manager to establish use rights. Please be aware that if such rights are established, you will be responsible for compliance according to the terms of your customer agreement. No other third parties may use this API without explicit approval from SAP Legal. Access to this documentation does not provide access to the API.

Contents

Products and Editions

Scope Usage

Name Description Endpoint
creditcardaccountnumber.read or creditcardaccount.read Reads credit card data from Concur Expense. GET

Dependencies

SAP Concur clients must purchase Concur Expense in order to use this API.

The user may use the following SAP Concur APIs to get additional information: * Profile v1 - Company

Access Token Usage

This API supports company level access tokens.

Get Credit Card Account Details

Returns the credit card number encrypted with the public key provided in the request.

Scopes

creditcardaccountnumber.read or creditcardaccount.read - Refer to Scope Usage for full details.

Request

GET https://{region}.api.concursolutions.com/detokenizer/v4/company/{companyUUID}/creditcard/{creditcardGUID}
Parameters
Name Type Format Description
pubkeyAlgorithm string - The RSA algorithm used by the PublicKey for credit card number encryption.
pubkeyFormat string - Public key format.
pubkey string - Public key.
companyUUID string - Company UUID.
creditcardGUID string - Credit card GUID.

Headers

Payload

Response

Status Codes

Headers

Payload

Example

Request

GET https://us.api.concursolutions.com/detokenizer/v4/company/d295261b-e624-442b-b771-9c7f00c1ed9a/creditcard/BB98EABE1DDA7B48B858CFDC7EEE2A10?pubkeyAlgorithm=rsa_pkcs7&pubkeyFormat=cert&pubkey=PUBLIC_KEY
Authorization: Bearer JWT_TOKEN
Accept: application/json

Response

HTTP/1.1 200 OK
concur-correlationid: 87de8598-dbd5-4aea-af9d-988efb61c468
Content-Type: application/json
Content-Length: 1270
{
 "accountNumber": "MIAGCSqGSIb3DQEHA6CAMIACAQAxgbUwgbICAQAwGzAPMQ0wCwYDVQQDDARUZXN0AghyaD1Uj9uSsDANBgkqhkiG9w0BAQEFAASBgAk0/9Yd5CQt5/6vQ1gO9aSivBJrv4AOAluZ876tqVI+fCZi7P1YojC4nTkvl358zfD3vXE3ehj14FfIPZlwmuVlSZF4ad5ni2B78fs5Jr6lxhG9iPU0FyFv+NhuIet/mpEaaX2CWB8CUwkTVdDyT5UjrwqsvYpRCwLz0Hx76BO8MIAGCSqGSIb3DQEHATAdBglghkgBZQMEAQIEEPo3PO3VplgQ4mN0L5KInPKggAQgkqu7zWslGq3uqw0G2WXkK0QA2p0YHQuwhEPT2JMF5mUAAAAAAAAAA"
}

Schema

Account Number

Name Type Format Description
accountNumber string - Encrypted credit card account number.

GROUND-TRANSPORTATION

Direct Connect - Ground Transportation

The Ground Transportation Direct Connect provides a method for Travel users to access the inventory of ground transportation service providers. This direct connect was originally designed for use by limo service providers, but can be used with all forms of ground transportation.

Once the ground transportation supplier has developed their interface with SAP Concur, their inventory will begin appearing in ground transportation searches by opted-in Travel users.

This callout differs from the inbound SAP Concur web services in the following ways:

NOTE: This direct connect was originally designed to work with Limo providers, but can support all types of ground transportation.

Products and Editions

Product Restrictions

This direct connect is only available to Travel Suppliers with Ground Transportation inventory. This direct connect is not supported in the SAP Concur mobile application.

SAP Concur products are highly configurable, and not all clients will have access to all features.

Partner developers must determine which configurations are required for their solution prior to the review process.

Configuration Process

The configuration process has the following steps:

  1. The Travel Supplier creates the application on their system that will accept the requests from SAP Concur and return the appropriate responses.
  2. The Travel Supplier creates the endpoint on their system that SAP Concur uses to access their inventory.
  3. SAP Concur creates a production company for the travel supplier.
  4. The Travel Supplier registers their application with SAP Concur by logging in to their production company.
  5. SAP Concur configures Travel to send requests to the endpoint.
  6. The Travel client opts in to the Ground Transportation callout using the Travel Configuration UI to allow their users to view and book the available inventory. Clients must contact SAP Concur to have this setting activated

Once the configuration is complete, the callout uses the following process:

  1. The user searches for ground transportation when creating an itinerary in Travel.
  2. Travel sends the search details to the endpoint, using the Post Search Request.
  3. The supplier returns the search results.
  4. If the user chooses to reserve the ride, Travel sends the Post Sell Request.
  5. The supplier returns the Post Sell Reply.

This callout can also be used to perform the following operations:

Authentication

Authentication between SAP Concur and the application connector is performed using OAuth.

Operations

Cancel Reservation

Post Reservation Detail Search

Post Reservation Sell

Post Transportation Search

Update Reservation with the Supplier

GDS Sell Formats

Sabre:
1 OTH LM 14MAY M GK1 DCA/PCI QA TEST/TEL 201 555 1212/RATE-$0.00/CONF-/PICKUP-209 MADISON ST SUITE 400 ALEXANDRIAVA 22314 AT 0900/DROPOFF-DCA AIRPORT AT 0915/203121365/RESERVATION L1

Apollo:
1 LIM ZM GK1  DCA 09MAY-/PCI QA TEST-TEL 2015551212/RATE-$0.00/CONF-/PICKUP-209 MADISON ST SUITE 400"ALEXANDRIA"VA"22314 AT 0900/DROPOFF-DCA AIRPORT/52695871/RESERVATION L1

Abacus:
1 OTH LM 14MAY M GK1 DCA/PCI QA TEST/TEL 201 555 1212/RATE-$0.00/CONF-/PICKUP-209 MADISON ST SUITE 400 ALEXANDRIAVA 22314 AT 0900/DROPOFF-DCA AIRPORT AT 0915/203121365/RESERVATION L1

Galileo:
TUR ZM AK1  SEA 15DEC-/FALCON DES-TEL 8666932526/RATE-50.00 HOURLY-2 HR MIN/CONF-/PU-18400  AT 0900/DO-SEA/771297634/RES

Amadeus:
2 MIS 1A HK1 LGA 13SEP-LMO CAPITAL LIMOUSINE/TEL-800 225 1656/RATE-USD24.00 FLAT/CONF-132625/PICKUP-55 WALL STREET NEW YORK NY 10005 AT 0530/DROPOFF- LGA AIRPORT AT 0600/RID-132625760

Direct Connect - Ground Transportation - Cancel a reservation

The Cancel Reservation operation is sent to the supplier to cancel a travel reservation on behalf of a user. The Ground Transportation direct connect sends the relevant information to a URI that the travel supplier maintains. The standard location is: https://{servername}/concur/groundtransportation. This URI is configured by the supplier when registering the partner application.

Request

URI

/concur/groundtransportation

Headers

Content-Type header (optional)

Accept header (optional)

Authorization header (required)

The Authorization header must include Base64 encoded basic authentication credentials (login ID and password). The login and password are established when the application connector is registered.

'Authorization: Basic {Base64 encoded LoginID:Password}'

Request Body

The request contains a CC_LimoCancelRequest parent element with the child elements listed in the following table:

Element Required/Optional Description
ReservationID Required The unique identifier for the reservation.

Example Request

POST /concur/groundtransportation HTTPS/1.1
Host: example.com
Authorization: Basic ...
Content-Type: application/xml
Content-Length: {length of content body}

<CC_LimoCancelRequest>
    <ReservationID>1234</ReservationID>
</CC_LimoCancelRequest>

Response

The supplier responds to the request by supplying the full reservation details, with the updated status.

Content Type

Response Schema

The response will include a CC_LimoCancelReply parent element, with the following child elements:

Element Required? Description
Error Y The error information, if an error occurred. This parent element contains the following child elements:
ErrorCode: The code for the error. Will contain one of the following values:
400: Credential related error
800: Reservation cannot be cancelled
900: Unknown error
ErrorSource: The source of the error.
ErrorDescription:The additional error information.
ReservationID N The identifier for the reservation.
Status N The status of the reservation. The value will be one of the following:
XB: Cancellation Requested
XA: Cancellation Accepted
XD: Cancellation Declined
ConfNum N The confirmation number for the reservation.
CancelPolicy N The cancellation policy for the reservation.
CancelNum N The cancellation number for the reservation.
PrimaryPassenger Y The passenger contact name for the reservation. This parent element contains the following child elements:
FirstName: The contact's first name.
LastName: The contact's last name.
Phone: The contact's phone number.
Phone2: The contact's backup phone number.
CellPhone: The contact's cell phone number.
EmailAddress: The contact's email address.
ServiceType Y The type of service requested. Will contain one of the following values:
100: Point to point
110: One way to airport
111: One way from airport
120: One way to train station
121: One way from train station
200: Hourly
300: Airport to airport
ClassOfService N The requested service class. Will contain one of the following values:
100: Normal
200: High
300: Highest
If this value is not provided by the user, it will default to 100.
PickupLocation Y The pick up location. This parent element contains the following child elements:
LocationType: One of the following: 100 - Address, 200 - Airport, 300 - Train station.
Airport: Refer to the Airport Elements table. Provided if the LocationType = 200.
TrainStation: Refer to the Train Station Elements table. Provided if the LocationType = 300.
Address: The street address of the location. Provided if the LocationType = 100.
City: The location city.
State: The location state. Preferably 2 characters, max 10 characters.
Country: The location's 2 character ISO 3166-1 alpha-2 country code. Example: US
PostalCode: The location postal code.
ExtraNotes: Additional notes about the location. Example: Ring doorbell, Holiday Inn, etc.
DropoffLocation Y The drop off location. This parent element contains the following child elements:
LocationType: One of the following: 100 - Address, 200 - Airport, 300 - Train station, 400 - As directed.
Airport: Refer to the Airport Elements table. Provided if the LocationType = 200.
TrainStation: Refer to the Train Station Elements table. Provided if the LocationType = 300.
Address: The street address of the location. Provided if the LocationType = 100.
City: The location city.
State: The location state.
Country: The location's 2 character ISO 3166-1 alpha-2 country code. Example: US
PostalCode: The location postal code.
ExtraNotes: Additional notes about the location. Example: Apartment Building, gravel driveway, etc.
StartDateTime Y The time, in GMT, that the reservation must begin. Format: 2015-05-19T18:00:00
EndDateTime N The time, in GMT that the reservation will end. Provided for hourly reservations. Format: 2015-05-19T18:00:00
PickupInstructions N Additional instructions about the pick up request.
DropoffInstructions N Additional instructions about the drop off request.
LanguageCode Y The language of the traveler. Will be one of the following options:
en: English
en-us: English (US)
en-gb: English (UK)
fr: French
fr-ca: French (Canadian)
de: German
pt: Portuguese
es: Spanish
nl: Dutch
it: Italian
ja: Japanese
pl: Polish
pt-br: Portuguese (Brazilian)
ru: Russian
hu: Hungarian
ko: Korean
sv: Swedish
zh-cn: Chinese
zh-tw: Traditional Chinese
Currency Y The 3-letter ISO 4217 currency code for the reservation amount.
NumPassengers N The number of passengers.
RequestedDriver N The name of the requested driver, if available.
SpecialServiceRequest N The details of the special service request, if available.
PickupServiceArrangement N The details of the pickup arrangement, if available.
DropoffServiceArrangement N The details of the dropoff arrangement, if available.
ExtraStopArrangement N The details of the extra stop arrangement, if available.
RateInfo Y The booked rate details. Refer to the Rate Information Elements table for more information.
Vehicle Y The vehicle details. This parent element contains the following child elements:
VehicleType: One of the following values:
100: Sedan
200: Limo
250: Stretch Limo
300: SUV
350: Stretch SUV
400: Van
450: Mini-Bus
500: Motor Coach
600: Shuttle
700: Trolley
800: Carriage
900: Any
Description: The vehicle description.
MaxPassengers: The maximum number of passengers for the vehicle. Must be greater than zero.
VehicleID: Information to identify the specific vehicle.
Vendor Y The reservation vendor. This parent element contains the following child elements:
VendorCode: The vendor code for the vendor.
VendorName: The vendor's name.
PhoneNumber: The vendor's phone number.
FormOfPayment Y The form of payment for the reservation. This parent element contains one of the following child elements:
CreditCard: If present, the passenger will pay with credit card. Refer to the Reply Credit Card Elements table for the child elements.
Cash: If present, the passenger will pay cash.
Check: If present, the passenger will pay with a check.
DirectBilling: If present, the passenger will pay through direct billing.
RateDisclaimer N Disclaimer text about the rate.
ProviderFeedback N Any additional feedback from the supplier.
AccountingInfo N The accounting information for the reservation. This parent element contains the following child elements:
AccountingField1 through AccountingField5: These fields contain detailed accounting information.

Rate Information Elements

Element Required? Description
RateID Y The rate identifier.
Rate Y The BasePrice + ServiceCharge + SurCharge + Tax
RateTypeCode Y The code for the rate type. Will be one of the following options:
F: Flat rate
H: Hourly
E: Estimated amount
N: Currently not available
CategoryCode N Extra information that will be passed back during sell request to help identify the rate.
Currency Y The 3-letter ISO 4217 currency code for the rate amount.
NoRateText N Explanation of rate type. Provided if RateTypeCode = N
MinHours N The minimum number of hours for the reservation.
DiscountType N The type of discount applied.
BasePrice N The reservation price without taxes, surcharges or service charges.
ServiceCharge N The service charge for the reservation.
SurCharge N This element contains the desc attribute, with text describing the reason for the surcharge. Example: <SurCharge desc="fuel">
Tax N The reservation tax.
ExtraPickupCharge N Any additional fees for the pickup service.
ExtraDropoffCharge N Any additional fees for the dropoff service.
OptionalExtraStopCharge N The charge for any additional stops.
OptionalExtraTimeCharge N The charge for each additional hour.

Reply Credit Card Elements

Element Required? Description
Type Y The card type.
Number Y The card number.
Expiration Y The card expiration date. Format: 2013-02-19

Example of Successful Response

HTTPS/1.1 200 OK
Content-Type: application/xml
Content-Length: {length of content body}

<CC_LimoCancelReply>
    <Error>
        <ErrorCode />
        <ErrorSource />
        <ErrorDescription />
    </Error>
    <ReservationID>1234</ReservationID>
    <Status>XB</Status>
    <ConfNum>4444</ConfNum>
    <CancelPolicy />
    <CancelNum>55555</CancelNum>
    <PrimaryPassenger>
        <FirstName>Chris</FirstName>
        <LastName>Miller</LastName>
        <Phone>5551234567</Phone>
        <Phone2>5551234568</Phone2>
        <CellPhone>5551234569</CellPhone>
        <EmailAddress>cmiller@example.com</EmailAddress>
    </PrimaryPassenger>
    <ServiceType>110</ServiceType>
    <ClassOfService />
    <PickupLocation>
        <LocationType>100</LocationType>
        <Airport>
            <AirportCode />
            <Flight>
                <CarrierCode />
                <FlightNumber />
                <ArrivalDateTime />
            </Flight>
        </Airport>
        <TrainStation>
            <StationCode />
            <StationName />
            <City />
            <State />
            <Train>
                <CarrierCode />
                <CarrierName />
                <TrainNumber />
                <ArrivalDateTime />
            </Train>
        </TrainStation>
        <Address>209 Madison St</Address>
        <City>Alexandria</City>
        <State>VA</State>
        <Country>US</Country>
        <PostalCode>22314</PostalCode>
        <ExtraNotes />
    </PickupLocation>
    <DropoffLocation>
        <LocationType>200</LocationType>
        <Airport>
            <AirportCode>DCA</AirportCode>
            <Flight>
                <CarrierCode>UA</CarrierCode>
                <FlightNumber>333</FlightNumber>
                <DepartureDateTime>2012-02-19T11:29:00</DepartureDateTime>
            </Flight>
        </Airport>
        <TrainStation>
            <StationCode />
            <StationName />
            <City />
            <State />
            <Train>
                <CarrierCode />
                <CarrierName />
                <TrainNumber />
                <DepartureDateTime />
            </Train>
        </TrainStation>
        <Address />
        <City />
        <State />
        <Country />
        <PostalCode />
        <ExtraNotes />
    </DropoffLocation>
    <StartDateTime>2012-02-19T09:00:00</StartDateTime>
    <EndDateTime />
    <PickupInstructions>pick me up</PickupInstructions>
    <DropoffInstructions>None</DropoffInstructions>
    <LanguageCode>en-us</LanguageCode>
    <Currency>USD</Currency>
    <NumPassengers>1</NumPassengers>
    <RequestedDriver />
    <SpecialServiceRequest />
    <PickupServiceArrangement />
    <DropoffServiceArrangement />
    <ExtraStopArrangement />
    <RateInfo>
        <RateID>5</RateID>
        <Rate>42.50</Rate>
        <RateTypeCode>E</RateTypeCode>
        <CategoryCode />
        <MinHours />
        <Currency>US</Currency>
        <NoRateText />
        <DiscountType />
        <BasePrice>35.00</BasePrice>
        <ServiceCharge>5.00</ServiceCharge>
        <SurCharge desc="fuel">1.00</SurCharge>
        <Tax>1.50</Tax>
        <ExtraPickupCharge />
        <ExtraDropoffCharge />
        <OptionalExtraStopCharge />
        <OptionalExtraTimeCharge />
        <Message />
    </RateInfo>
    <RateDisclaimer />
    <Vehicle>
        <VehicleType>100</VehicleType>
        <Description>This is a Sedan.</Description>
        <MaxPassengers>1</MaxPassengers>
        <VehicleID>12</VehicleID>
    </Vehicle>
    <Vendor>
        <VendorCode>LML</VendorCode>
        <VendorName>LimoVendor</VendorName>
        <PhoneNumber>4354654654</PhoneNumber>
    </Vendor>
    <ProviderFeedback />
    <FormOfPayment>
        <Cash />
        <Check />
        <DirectBilling />
        <CreditCard>
            <Type>VI</Type>
            <Number>XXXXXXXXXXXX1111</Number>
            <Expiration>2013-02-19</Expiration>
        </CreditCard>
    </FormOfPayment>
    <AccountingInfo>
        <AccountingField1>715</AccountingField1>
        <AccountingField2>temp@outtask.com</AccountingField2>
        <AccountingField3>11</AccountingField3>
        <AccountingField4>Development</AccountingField4>
        <AccountingField5/>
    </AccountingInfo>
</CC_LimoCancelReply>

Direct Connect - Ground Transportation - Post a reservation detail search

Request

The following request is sent to the supplier when the Travel user selects a ground transportation reservation to get additional details.

URI

The Ground Transportation direct connect sends the relevant information to a URI that the travel supplier maintains. The standard location is:

https://{servername}/concur/groundtransportation

The URI is configured by the supplier when registering the partner application.

Request Headers - Required

Authorization header with OAuth credentials. Refer to the OAuth documentation for more information.

Request Headers - Optional

None

Request Body

The request will contain a CC_LimoReservationDetailRequest parent element, containing the following child element:

Element Name Required/Optional Data Type Description
ReservationID The unique identifier for the reservation. Returned in the ReservationID element by the response of the Post Reservation Sell function.

XML Example Request

POST /concur/groundtransportation HTTPS/1.1
Host: example.com
Authorization: Basic ...
Content-Type: application/xml
Content-Length: {length of content body}
<CC_LimoReservationDetailRequest>
 <ReservationID>1234</ReservationID>
</CC_LimoReservationDetailRequest>

Response

The supplier responds to the request by supplying the full reservation details.

Content Type

application/xml

Response Schema

The response will include a CC_LimoReservationDetailReply parent element, with the following child elements:

Element Name Required/Optional Data Type Description
Error Y The error information, if an error occurred. For information about the child elements of this parent element, see the Error elements table.
ReservationID N The identifier for the reservation.
Status N The status of the reservation. The value will be one of the following:
RB: Reservation Pending
RA: Reservation Accepted (Reserved)
RD: Reservation Declined
XB: Cancellation Pending
XA: Cancellation Confirmed (Cancelled)
XD: Cancellation Declined
ConfNum N The confirmation number for the reservation.
CancelPolicy N The cancellation policy for the reservation.
CancelNum N The cancellation number for the reservation.
PrimaryPassenger Y The passenger contact name for the reservation. For information about the child elements of this parent element, see the PrimaryPassenger elements table.
ServiceType Y The type of service requested. Will contain one of the following values:
100: Point to point
110: One way to airport
111: One way from airport
120: One way to train station
121: One way from train station
200: Hourly
300: Airport to airport
ClassOfService N The requested service class. Will contain one of the following values:
100: Normal
200: High
300: Highest
If this value is not provided by the user, it will default to 100.
PickupLocation Y The pick up location. For information about the child elements of this parent element, see the PickupLocation elements table.
DropoffLocation Y The drop off location. For information about the child elements of this parent element, see the DropoffLocation elements table.
StartDateTime Y The time, in GMT, that the reservation must begin. Format: 2015-05-19T18:00:00
EndDateTime N The time, in GMT that the reservation will end. Provided for hourly reservations. Format: 2015-05-19T18:00:00
PickupInstructions N Additional instructions about the pick up request.
DropoffInstructions N Additional instructions about the drop off request.
LanguageCode Y The language of the traveler. Will be one of the following options:
en: English
en-us: English (US)
en-gb: English (UK)
fr: French
fr-ca: French (Canadian)
de: German
pt: Portuguese
es: Spanish
nl: Dutch
it: Italian
ja: Japanese
pl: Polish
bt-br: Portuguese (Brazilian)
ru: Russian
hu: Hungarian
ko: Korean
sv: Swedish
zh-cn: Chinese
zh-tw: Traditional Chinese
Currency Y The 3-letter ISO 4217 currency code for the reservation amount.
NumPassengers N The number of passengers.
RequestedDriver N The name of the requested driver, if available.
SpecialServiceRequest N The details of the special service request, if available.
PickupServiceArrangement N The details of the pickup arrangement, if available.
DropoffServiceArrangement N The details of the dropoff arrangement, if available.
ExtraStopArrangement N The details of the extra stop arrangement, if available.
RateInfo Y The booked rate details. Refer to the Rate Information elements table for more information.
Vehicle Y The vehicle details. For information about the child elements of this parent element, see the Vehicle elements table.
Vendor Y The reservation vendor. For information about the child elements of this parent element, see the Vendor elements table.
FormOfPayment Y The form of payment for the reservation. For information about the child elements of this parent element, see the FormOfPayment elements table.
RateDisclaimer N Disclaimer text about the rate.
ProviderFeedback N Any additional feedback from the supplier.
AccountingInfo N The accounting information for the reservation. This parent element contains the following child elements: AccountingField1 through AccountingField5

Error Child Elements

Element Name Required/Optional Data Type Description
ErrorCode The code for the error. Will contain one of the following values:
400: Credential related error
700: Reservation not available
900: Unknown error
ErrorSource The source of the error.
ErrorDescription The additional error information.

PrimaryPassenger Child Element

Element Name Required/Optional Data Type Description
FirstName The contact's first name.
LastName The contact's last name.
Phone The contact's phone number.
Phone2 The contact's backup phone number.
CellPhone The contact's cell phone number.
EmailAddress The contact's email address.

PickupLocation

Element Name Required/Optional Data Type Description
LocationType One of the following: 100 - Address, 200 - Airport, 300 - Train station.
Airport Refer to the Airport elements table. Provided if the LocationType = 200.
TrainStation Refer to the Train Station elements table. Provided if the LocationType = 300.
Address The street address of the location. Provided if the LocationType = 100.
City The location city.
State The location state. Preferably 2 characters, max 10 characters.
Country The location's 2 character ISO 3166-1 alpha-2 country code. Example: US
PostalCode The location postal code.
ExtraNotes Additional notes about the location. Example: Ring doorbell, Holiday Inn, etc.

DropoffLocation

Element Name Required/Optional Data Type Description
LocationType One of the following: 100 - Address, 200 - Airport, 300 - Train station, 400 - As directed.
Airport Refer to the Airport elements table. Provided if the LocationType = 200.
TrainStation Refer to the Train Station elements table. Provided if the LocationType = 300.
Address The street address of the location. Provided if the LocationType = 100.
City The location city.
State The location state. Preferably 2 characters, max 10 characters.
Country The location's 2 character ISO 3166-1 alpha-2 country code. Example: US
PostalCode The location postal code.
ExtraNotes Additional notes about the location. Example: Apartment Building, gravel driveway, etc.

Vehicle Child Elements

Element Name Required/Optional Data Type Description
VehicleType One of the following values:
100: Sedan
200: Limo
250: Stretch Limo
300: SUV
350: Stretch SUV
400: Van
450: Mini-Bus
500: Motor Coach
600: Shuttle
700: Trolley
800: Carriage
900: Any
Description The vehicle description.
MaxPassengers The maximum number of passengers for the vehicle. Must be greater than zero.
VehicleID Information to identify the specific vehicle.

Vendor Child Elements

Element Name Required/Optional Data Type Description
VendorCode The vendor code for the vendor.
VendorName The vendor's name.
PhoneNumber The vendor's phone number.

FormOfPayment Child Elements

Element Name Required/Optional Data Type Description
CreditCard If present, the passenger will pay with credit card. Refer to the Reply Credit Card Elements table for the child elements.
Cash If present, the passenger will pay cash.
Check If present, the passenger will pay with a check.
DirectBilling If present, the passenger will pay through direct billing.

Rate Information Elements

Element Name Required/Optional Data Type Description
RateID Y The rate identifier.
Rate Y The BasePrice + ServiceCharge + SurCharge + Tax
RateTypeCode Y The code for the rate type. Will be one of the following options:
F: Flat rate
H: Hourly
E: Estimated amount
N: Currently not available
CategoryCode N Extra information that will be passed back during sell request to help identify the rate.
Currency Y The 3-letter ISO 4217 currency code for the rate amount.
NoRateText N Explanation of rate type. Provided if RateTypeCode = N
MinHours N The minimum number of hours for the reservation.
DiscountType N The type of discount applied.
BasePrice N The reservation price without taxes, surcharges or service charges.
ServiceCharge N The service charge for the reservation.
SurCharge N This element contains the desc attribute, with text describing the reason for the surcharge. Example: <SurCharge desc="fuel">
Tax N The reservation tax.
ExtraPickupCharge N Any additional fees for the pickup service.
ExtraDropoffCharge N Any additional fees for the drop off service.
OptionalExtraStopCharge N The charge for any additional stops.
OptionalExtraTimeCharge N The charge for each additional hour.

Reply Credit Card Elements

Element Name Required/Optional Data Type Description
Type Y The card type.
Number Y The card number.
Expiration Y The card expiration date. Format: 2013-02-19.

Airport Elements

Element Name Required/Optional Data Type Description
AirportCode The IATA code for the airport.
Flight The flight information. For information about the child elements of this parent element, see the Flight elements table.

Flight Child Elements

Element Name Required/Optional Data Type Description
CarrierCode The airline code.
FlightNumber The flight number.
ArrivalDateTime The flight arrival time. Only provided for the PickupLocation element. Format: 2015-05-19T18:00:00
DepartureDateTime The flight departure time. Only provided for the DropoffLocation element. Format: 2015-05-19T18:00:00

Train Station Elements

Element Name Required/Optional Data Type Description
StationCode The station code.
StationName The name of the station.
City The city the station is located in.
State The state the station is located in. Preferably 2 characters, max 10 characters.
Train The train information. For information about the child elements of this parent element, see the Train elements table.

Train Child Elements

Element Name Required/Optional Data Type Description
CarrierCode The code of the train carrier.
CarrierName The name of the train carrier.
TrainNumber The train number.
ArrivalDateTime The train arrival time. Only provided for the PickupLocation element. Format: 2015-05-19T18:00:00
DepartureDateTime The train departure time. Only provided for the DropoffLocation element. Format: 2015-05-19T18:00:00

XML Example of Successful Response

HTTPS/1.1 200 OK
Content-Type: application/xml
Content-Length: {length of content body}
<CC_LimoReservationDetailReply>
  <Error>
    <ErrorCode />
    <ErrorSource />
    <ErrorDescription />
  </Error>
  <ReservationID>1234</ReservationID>
  <Status>RB</Status>
  <ConfNum>4444</ConfNum>
  <CancelPolicy />
  <CancelNum>55555</CancelNum>
  <PrimaryPassenger>
    <FirstName>Chris</FirstName>
    <LastName>Miller</LastName>
    <Phone>5551234567</Phone>
    <Phone2>5551234568</Phone2>
    <CellPhone>5551234569</CellPhone>
    <EmailAddress>cmiller@example.com</EmailAddress>
  </PrimaryPassenger>
  <ServiceType>110</ServiceType>
  <ClassOfService />
  <PickupLocation>
    <LocationType>100</LocationType>
    <Airport>
      <AirportCode />
      <Flight>
        <CarrierCode />
        <FlightNumber />
        <ArrivalDateTime />
      </Flight>
    </Airport>
    <TrainStation>
      <StationCode />
      <StationName />
      <City />
      <State />
      <Train>
        <CarrierCode />
        <CarrierName />
        <TrainNumber />
        <ArrivalDateTime />
      </Train>
    </TrainStation>
    <Address>209 Madison St</Address>
    <City>Alexandria</City>
    <State>VA</State>
    <Country>US</Country>
    <PostalCode>22314</PostalCode>
    <ExtraNotes />
  </PickupLocation>
  <DropoffLocation>
    <LocationType>200</LocationType>
    <Airport>
      <AirportCode>DCA</AirportCode>
      <Flight>
        <CarrierCode>UA</CarrierCode>
        <FlightNumber>333</FlightNumber>
        <DepartureDateTime>2012-02-19T11:29:00</DepartureDateTime>
      </Flight>
    </Airport>
    <TrainStation>
      <StationCode />
      <StationName />
      <City />
      <State />
      <Train>
        <CarrierCode />
        <CarrierName />
        <TrainNumber />
        <DepartureDateTime />
      </Train>
    </TrainStation>
    <Address />
    <City />
    <State />
    <Country />
    <PostalCode />
    <ExtraNotes />
  </DropoffLocation>
  <StartDateTime>2012-02-19T09:00:00</StartDateTime>
  <EndDateTime />
  <PickupInstructions>pick me up</PickupInstructions>
  <DropoffInstructions>None</DropoffInstructions>
  <LanguageCode>en-us</LanguageCode>
  <Currency>USD</Currency>
  <NumPassengers>1</NumPassengers>
  <RequestedDriver />
  <SpecialServiceRequest />
  <PickupServiceArrangement />
  <DropoffServiceArrangement />
  <ExtraStopArrangement />
  <RateInfo>
    <RateID>5</RateID>
    <Rate>42.50</Rate>
    <RateTypeCode>E</RateTypeCode>
    <CategoryCode />
    <MinHours />
    <Currency>USD</Currency>
    <NoRateText />
    <DiscountType />
    <BasePrice>35.00</BasePrice>
    <ServiceCharge>5.00</ServiceCharge>
    <SurCharge desc="fuel">1.00</SurCharge>
    <Tax>1.50</Tax>
    <ExtraPickupCharge />
    <ExtraDropoffCharge />
    <OptionalExtraStopCharge />
    <OptionalExtraTimeCharge />
    <Message />
  </RateInfo>
  <RateDisclaimer />
  <Vehicle>
    <VehicleType>100</VehicleType>
    <Description>This is a Sedan.</Description>
    <MaxPassengers>1</MaxPassengers>
    <VehicleID>12</VehicleID>
  </Vehicle>
  <Vendor>
    <VendorCode>LML</VendorCode>
    <VendorName>LimoVendor</VendorName>
    <PhoneNumber>4354654654</PhoneNumber>
  </Vendor>
  <ProviderFeedback />
  <FormOfPayment>
    <Cash />
    <Check />
    <DirectBilling />
    <CreditCard>
      <Type>VI</Type>
      <Number>XXXXXXXXXXXX1111</Number>
      <Expiration>2013-02-19</Expiration>
    </CreditCard>
  </FormOfPayment>
  <AccountingInfo>
    <AccountingField1>715</AccountingField1>
    <AccountingField2>temp@outtask.com</AccountingField2>
    <AccountingField3>11</AccountingField3>
    <AccountingField4>Development</AccountingField4>
    <AccountingField5/>
  </AccountingInfo>
</CC_LimoReservationDetailReply>

Direct Connect - Ground Transportation - Post a reservation sell request

A post reservation sell request is sent when a Travel user attempts to book a ground transportation reservation.

Request

Supported Accept Types

application/xml

Request URI

The Ground Transportation direct connect sends the relevant information to a URI that the travel supplier maintains. The standard location is:

https://{servername}/concur/groundtransportation

The URI is configured by the supplier when registering the partner application.

Headers

Authorization Header

Authentication header with Base64 encoded basic authentication credentials (login ID and password) is required. The basic authentication credentials are established during the application review process.

Authorization: Basic {Base64 encoded LoginID:Password}

Request Body

The request will contain a CC_LimoSellRequest parent element, containing the following child elements.

CorporateClient

The corporate client the booking is on behalf of. This parent element contains the following child element:

Booker

The user booking the reservation. This parent element contains the following child elements:

PrimaryPassenger

The passenger contact name for the reservation. This parent element contains the following child elements:

ServiceType

The type of service requested. Will contain one of the following values:

ClassOfService

The requested service class. Will contain one of the following values:

If this value is not provided by the user, it will default to 100

PickupLocation

The pick up location. This parent element contains the following child elements:

DropoffLocation

The drop off location. This parent element contains the following child elements:

StartDateTime

The time, in GMT, that the reservation must begin. Format: 2015-05-19T18:00:00

EndDateTime

The time, in GMT that the reservation will end. Provided for hourly reservations. Format: 2015-05-19T18:00:00

PickupInstructions

Additional instructions about the pick up request.

DropoffInstructions

Additional instructions about the drop off request.

LanguageCode

The language of the traveler. Will be one of the following options:

Currency

The 3-letter ISO 4217 currency code for the reservation amount.

NumPassengers

The number of passengers.

DiscountCode

The discount code information. This parent element contains the following child elements:

RateInfo

The booked rate. This parent element contains the following child elements:

Vehicle

The vehicle details. This parent element contains the following child elements:

Vendor

The reservation vendor. This parent element contains the following child element:

FormOfPayment

The form of payment for the reservation. This parent element contains one of the following child elements:

RequestedDriver

The name of the requested driver, if available.

SpecialServiceRequest

The details of the special service request, if available.

PickupServiceArrangement

The details of the pickup arrangement, if available.

DropoffServiceArrangement

The details of the dropoff arrangement, if available.

ExtraStopArrangement

The details of the extra stop arrangement, if available.

RequestedDriver

The name of the requested driver, if available.

Airport Elements

AirportCode

The IATA code for the airport.

Flight: The flight information. This parent element contains the following child elements: * CarrierCode: The airline code. * FlightNumber: The flight number. * ArrivalDateTime: The flight arrival time. Only provided for the PickupLocation element. Format: 2015-05-19T18:00:00 * DepartureDateTime: The flight departure time. Only provided for the DropoffLocation element. Format: 2015-05-19T18:00:00

Train Station Elements

StationCode

The station code.

StationName

The name of the station.

City

The city the station is located in.

State

The state the station is located in. Preferably 2 characters, max 10 characters.

Train

The train information. This parent element contains the following child elements:

Credit Card Elements

Type

The card type.

Number

The card number.

Expiration

The card expiration date. Format: 2013-02-19

Name

The name on the card.

Address

The street information of the billing address of the car.

City

The city of the billing address of the car.

State

The state of the billing address of the car. Preferably 2 characters, max 10 characters.

Country

The country of the billing address of the car.

PostalCode

The postal code of the billing address of the car.

XML Example Request

POST /concur/groundtransportation HTTPS/1.1
Host: example.com
Authorization: Basic ...
Content-Type: application/xml
Content-Length: {length of content body}

<CC_LimoSellRequest>
  <CorporateClient>
      <CompanyCode>339</CompanyCode>
  </CorporateClient>
  <Booker>
      <UserID>55414</UserID>
      <EmailAddress>cmiller@example.com</EmailAddress>
      <Phone>5551234567</Phone>
  </Booker>
  <PrimaryPassenger>
      <FirstName>Chris</FirstName>
      <LastName>Miller</LastName>
      <Phone>5551234567</Phone>
      <Phone2>5551234568</Phone2>
      <CellPhone>5551234569</CellPhone>
      <EmailAddress>cmiller@example.com</EmailAddress>
  </PrimaryPassenger>
  <ServiceType>110</ServiceType>
  <ClassOfService>100</ClassOfService>
  <StartDateTime>2012-02-19T09:00:00</StartDateTime>
  <EndDateTime />
  <PickupInstructions>pick me up</PickupInstructions>
  <DropoffInstructions>None</DropoffInstructions>
  <LanguageCode>en-us</LanguageCode>
  <RateInfo>
      <RateID>1</RateID>
      <Rate>42.50</Rate>
      <RateTypeCode>100</RateTypeCode>
      <CategoryCode />
      <Currency>USD</Currency>
  </RateInfo>
  <Vehicle>
      <VehicleType>Sedan</VehicleType>
      <Description>This is a Sedan.</Description>
      <MaxPassengers>1</MaxPassengers>
      <VehicleID>12</VehicleID>
  </Vehicle>
  <Vendor>
      <VendorCode>LML</VendorCode>
      <VendorName>LimoVendor</VendorName>
      <PhoneNumber>4354654654</PhoneNumber>
  </Vendor>
  <FormOfPayment>
      <CreditCard>
          <Type>VI</Type>
          <Number>xxxxxxxxxxxx1111</Number>
          <Expiration>2013-02-19</Expiration>
          <NameOnCard />
          <Address>209 MADISON ST. #400</Address>
          <City>ALEXANDRIA</City>
          <State>VA</State>
          <Country>US</Country>
          <PostalCode>22314</PostalCode>
      </CreditCard>
  </FormOfPayment>
  <RequestedDriver />
  <AccountingInfo>
      <AccountingField1>715</AccountingField1>
      <AccountingField2>temp@outtask.com</AccountingField2>
      <AccountingField3>11</AccountingField3>
      <AccountingField4>Development</AccountingField4>
      <AccountingField5/>
  </AccountingInfo>
</CC_LimoSellRequest>

Response

The supplier responds to the Sell request by returning the details of the booked reservation.

Supported Content Types

application/xml

Content Body

The response will include a CC_LimoSellReply parent element, with the following child elements:

Element Required? Description
Error Y The error information, if an error occurred. For information about the child elements of this parent element, see the Error elements table below.
ReservationID N The identifier for the reservation.
Status N The status of the reservation. The value will be one of the following:
RB: Reservation Pending
RA: Reservation Accepted (Reserved)
RD: Reservation Declined
ConfNum N The confirmation number for the reservation.
CancelPolicy N The cancellation policy for the reservation.
CancelNum N The cancellation number for the reservation.
PrimaryPassenger Y The passenger contact name for the reservation. For information about the child elements of this parent element, see the PrimaryPassenger elements table below.
ServiceType Y The type of service requested. Will contain one of the following values:
100: Point to point
110: One way to airport
111: One way from airport
120: One way to train station
121: One way from train station
200: Hourly
300: Airport to airport
ClassOfService N The requested service class. Will contain one of the following values:
100: Normal
200: High
300: Highest

If this value is not provided by the user, it will default to 100.
PickupLocation Y The pick up location. For information about the child elements of this parent element, see the PickupLocation elements table below.
DropoffLocation Y The drop off location. For information about the child elements of this parent element, see the DropoffLocation elements table below.
StartDateTime Y The time, in GMT, that the reservation must begin. Format: 2015-05-19T18:00:00
EndDateTime N The time, in GMT that the reservation will end. Provided for hourly reservations. Format: 2015-05-19T18:00:00
PickupInstructions N Additional instructions about the pick up request.
DropoffInstructions N Additional instructions about the drop off request.
LanguageCode Y The language of the traveler. Will be one of the following options:
en: English
en-us: English (US)
en-gb: English (UK)
fr: French
fr-ca: French (Canadian)
de: German
pt: Portuguese
es: Spanish
nl: Dutch
it: Italian
ja: Japanese
pl: Polish
pt-br: Portuguese (Brazilian)
ru: Russian
hu: Hungarian
ko: Korean
sv: Swedish
zh-cn: Chinese
zh-tw: Traditional Chinese
Currency Y The 3-letter ISO 4217 currency code for the reservation amount.
NumPassengers N The number of passengers.
RequestedDriver N The name of the requested driver, if available.
SpecialServiceRequest N The details of the special service request, if available.
PickupServiceArrangement N The details of the pickup arrangement, if available.
DropoffServiceArrangement N The details of the dropoff arrangement, if available.
ExtraStopArrangement N The details of the extra stop arrangement, if available.
RateInfo Y The booked rate details. Refer to the Rate Information elements table below for more information.
Vehicle Y The vehicle details. For information about the child elements of this parent element, see the Vehicle elements table below.
Vendor Y The reservation vendor. For information about the child elements of this parent element, see the Vendor elements table below.
FormOfPayment Y The form of payment for the reservation. For information about the child elements of this parent element, see the FormOfPayment elements table below.
RateDisclaimer N Disclaimer text about the rate.
ProviderFeedback N Any additional feedback from the supplier.
AccountingInfo N The accounting information for the reservation. This parent element contains one or more AccountingField elements: AccountingField1 through AccountingField5. These fields contain detailed accounting information.

Error Elements

Element Description
ErrorCode The code for the error. Will contain one of the following values:
100: Pickup/dropoff location related error
200: Pickup/dropoff time related error
300: Other request parameters related error
400: Credential related error
500: No rate/service available
600: FOP related error
900: Unknown error
ErrorSource The source of the error.
ErrorDescription The additional error information.

PrimaryPassenger Elements

Element Description
FirstName The contact's first name.
LastName The contact's last name.
Phone The contact's phone number.
Phone2 The contact's backup phone number.
CellPhone The contact's cell phone number.
EmailAddress The contact's email address.

Rate Information Elements

Element Name Required? Data Type Description
RateID Y The rate identifier.
Rate Y The BasePrice + ServiceCharge + SurCharge + Tax
RateTypeCode Y The code for the rate type. Will be one of the following options:
F: Flat rate
H: Hourly
E: Estimated amount
N: Currently not available
CategoryCode N Extra information that will be passed back during sell request to help identify the rate.
Currency Y The 3-letter ISO 4217 currency code for the rate amount.
NoRateText N Explanation of rate type. Provided if RateTypeCode = N
MinHours N The minimum number of hours for the reservation.
DiscountType N The type of discount applied.
BasePrice N The reservation price without taxes, surcharges or service charges.
ServiceCharge N The service charge for the reservation.
SurCharge N This element contains the desc attribute, with text describing the reason for the surcharge. Example: <SurCharge desc="fuel">
Tax N The reservation tax.
ExtraPickupCharge N Any additional fees for the pickup service.
ExtraDropoffCharge N Any additional fees for the drop off service.
OptionalExtraStopCharge N The charge for any additional stops.
OptionalExtraTimeCharge N The charge for each additional hour.

Vehicle Elements

Element Description
VehicleType One of the following values:
100: Sedan
200: Limo
250: Stretch Limo
300: SUV
350: Stretch SUV
400: Van
450: Mini-Bus
500: Motor Coach
600: Shuttle
700: Trolley
800: Carriage
900: Any
VehicleID Information to identify the specific vehicle.

Vendor Elements

Element Description
VendorCode The vendor code for the vendor.
VendorName The vendor's name.
PhoneNumber The vendor's phone number.

FormOfPayment Elements

Element Description
CreditCard If present, the passenger will pay with credit card. Refer to the Reply Credit Card elements table for the child elements.
Cash If present, the passenger will pay cash.
Check If present, the passenger will pay with a check.
DirectBilling If present, the passenger will pay through direct billing.

Reply Credit Card Elements

Element Name Required? Description
Type Y The card type.
Number Y The card number.
Expiration Y The card expiration date. Format: 2013-02-19

XML Example of Successful Response

HTTPS/1.1 200 OK
Content-Type: application/xml
Content-Length: {length of content body}

<CC_LimoSellReply>
  <Error>
      <ErrorCode />
      <ErrorSource />
      <ErrorDescription />
  </Error>
  <ReservationID>1234</ReservationID>
  <Status>RB</Status>
  <ConfNum>4444</ConfNum>
  <CancelPolicy />
  <CancelNum>55555</CancelNum>
  <PrimaryPassenger>
      <FirstName>Chris</FirstName>
      <LastName>Miller</LastName>
      <Phone>5551234567</Phone>
      <Phone2>5551234568</Phone2>
      <CellPhone>5551234569</CellPhone>
      <EmailAddress>cmiller@example.com</EmailAddress>
  </PrimaryPassenger>
  <ServiceType>110</ServiceType>
  <ClassOfService />
  <PickupLocation>
      <LocationType>100</LocationType>
      <Airport>
          <AirportCode />
          <Flight>
              <CarrierCode />
              <FlightNumber />
              <ArrivalDateTime />
          </Flight>
      </Airport>
      <TrainStation>
          <StationCode />
          <StationName />
          <City />
          <State />
          <Train>
              <CarrierCode />
              <CarrierName />
              <TrainNumber />
              <ArrivalDateTime />
          </Train>
      </TrainStation>
      <Address>209 Madison St</Address>
      <City>Alexandria</City>
      <State>VA</State>
      <Country>US</Country>
      <PostalCode>22314</PostalCode>
      <ExtraNotes />
  </PickupLocation>
  <DropoffLocation>
      <LocationType>200</LocationType>
      <Airport>
          <AirportCode>DCA</AirportCode>
          <Flight>
              <CarrierCode>UA</CarrierCode>
              <FlightNumber>333</FlightNumber>
              <DepartureDateTime>2012-02-19T11:29:00</DepartureDateTime>
          </Flight>
      </Airport>
      <TrainStation>
          <StationCode />
          <StationName />
          <City />
          <State />
          <Train>
              <CarrierCode />
              <CarrierName />
              <TrainNumber />
              <DepartureDateTime />
          </Train>
      </TrainStation>
      <Address />
      <City />
      <State />
      <Country />
      <PostalCode />
      <ExtraNotes />
  </DropoffLocation>
  <StartDateTime>2012-02-19T09:00:00</StartDateTime>
  <EndDateTime />
  <PickupInstructions>pick me up</PickupInstructions>
  <DropoffInstructions>None</DropoffInstructions>
  <LanguageCode>en-us</LanguageCode>
  <Currency>USD</Currency>
  <NumPassengers>1</NumPassengers>
  <RequestedDriver />
  <SpecialServiceRequest />
  <PickupServiceArrangement />
  <DropoffServiceArrangement />
  <ExtraStopArrangement />
  <RateInfo>
      <RateID>5</RateID>
      <Rate>42.50</Rate>
      <RateTypeCode>E</RateTypeCode>
      <CategoryCode />
      <MinHours />
      <Currency>US</Currency>
      <NoRateText />
      <DiscountType />
      <BasePrice>35.00</BasePrice>
      <ServiceCharge>5.00</ServiceCharge>
      <SurCharge desc="fuel">1.00</SurCharge>
      <Tax>1.50</Tax>
      <ExtraPickupCharge />
      <ExtraDropoffCharge />
      <OptionalExtraStopCharge />
      <OptionalExtraTimeCharge />
      <Message />
  </RateInfo>
  <RateDisclaimer />
  <Vehicle>
      <VehicleType>100</VehicleType>
      <Description>This is a Sedan.</Description>
      <MaxPassengers>1</MaxPassengers>
      <VehicleID>12</VehicleID>
  </Vehicle>
  <Vendor>
      <VendorCode>LML</VendorCode>
      <VendorName>LimoVendor</VendorName>
      <PhoneNumber>4354654654</PhoneNumber>
  </Vendor>
  <ProviderFeedback />
  <FormOfPayment>
      <Cash />
      <Check />
      <DirectBilling />
      <CreditCard>
          <Type>VI</Type>
          <Number>XXXXXXXXXXXX1111</Number>
          <Expiration>2013-02-19</Expiration>
      </CreditCard>
  </FormOfPayment>
  <AccountingInfo>
      <AccountingField1>715</AccountingField1>
      <AccountingField2>temp@outtask.com</AccountingField2>
      <AccountingField3>11</AccountingField3>
      <AccountingField4>Development</AccountingField4>
      <AccountingField5/>
  </AccountingInfo>
</CC_LimoSellReply>

Direct Connect - Ground Transportation - Post a transportation search

A post transportation search request is sent when the Travel user searches for ground transportation.

Request

URI

The Ground Transportation direct connect sends the relevant information to a URI that the travel supplier maintains. The standard location is:

https://{servername}/concur/groundtransportation

The URI is configured by the supplier when registering the partner application.

Headers

Accept Header

application/xml

Authorization Header

Authorization header with OAuth credentials.

Request Body

The request will contain a CC_LimoSearchRequest parent element, containing the following child elements.

ServiceType: The type of service requested. Will contain one of the following values:

100: Point to point
110: One way to airport
111: One way from airport
120: One way to train station
121: One way from train station
200: Hourly
300: Airport to airport

ClassOfService: The requested service class. Will contain one of the following values:

100: Normal
200: High
300: Highest

If this value is not provided by the user, it will default to 100.

PickupLocation: The pick up location. This parent element contains the following child elements:

PickupLocation Elements

Element Description
LocationType One of the following: 100 - Address, 200 - Airport, 300 - Train station.
Airport Refer to the Airport Elements table. Provided if the LocationType = 200.
TrainStation Refer to the Train Station Elements table. Provided if the LocationType = 300.
Address The street address of the location. Provided if the LocationType = 100.
City The location city.
State The location state. Preferably 2 characters, max 10 characters.
Country The location's 2 character ISO 3166-1 alpha-2 country code. Example: US
PostalCode The location postal code.
ExtraNotes Additional notes about the location. Example: Ring doorbell, Holiday Inn, etc.

DropoffLocation: The drop off location. This parent element contains the following child elements:

DropoffLocation Elements

Element Description
LocationType One of the following: 100 - Address, 200 - Airport, 300 - Train station.
Airport Refer to the Airport Elements table. Provided if the LocationType = 200.
TrainStation Refer to the Train Station Elements table. Provided if the LocationType = 300.
Address The street address of the location. Provided if the LocationType = 100.
City The location city.
State The location state. Preferably 2 characters, max 10 characters.
Country The location's 2 character ISO 3166-1 alpha-2 country code. Example: US
PostalCode The location postal code.
ExtraNotes Additional notes about the location. Example: Apartment building, gravel driveway, etc.

StartDateTime: The time, in GMT, that the reservation must begin. Format: 2015-05-19T18:00:00

EndDateTime: The time, in GMT that the reservation will end. Provided for hourly reservations. Format: 2015-05-19T18:00:00

PickupInstructions: Additional instructions about the pick up request.

DropoffInstructions: Additional instructions about the drop off request.

LanguageCode: The language of the traveler. Will be one of the following options:

en: English
en-us: English (US)
en-gb: English (UK)
fr: French
fr-ca: French (Canadian)
de: German
pt: Portuguese
es: Spanish
nl: Dutch
it: Italian
ja: Japanese
pl: Polish
pt-br: Portuguese (Brazilian)
ru: Russian
hu: Hungarian
ko: Korean
sv: Swedish
zh-cn: Chinese
zh-tw: Traditional Chinese

Currency: The 3-letter ISO 4217 currency code for the reservation amount.

NumPassengers: The number of passengers.

VehicleType: The type of vehicle requested. Will be one of the following options:

100: Sedan
200: Limo
201: Stretch Limo
300: SUV
301: Stretch SUV
400: Van
401: Mini-Bus
402: Bus
500: Motor Coach
501: Antique/Classic
502: Trolley
503: Carriage
600: Shuttle
900: Any

DiscountCode: The discount code information. This parent element contains the following child elements:

DiscountCode Elements

Element Description
CorporateID The user's corporate ID.
VendorCode The user's vendor code.
DiscountNumber The user's discount number.

Airport Elements

AirportCode: The IATA Code for the airport.

Flight: The flight information. This parent element contains the following child elements:

Flight Elements

Element Description
CarrierCode The airline code.
FlightNumber The flight number.
ArrivalDateTime The flight arrival time. Only provided for the PickupLocation element. Format: 2015-05-19T18:00:00
DepartureDateTime The flight departure time. Only provided for the DropoffLocation element. Format: 2015-05-19T18:00:00

Train Station Elements

Element Description
StationCode The station code.
StationName The name of the station.
City The city the station is located in.
State The state the station is located in. Preferably 2 characters, max 10 characters.
Train The train information. This parent element contains the following child elements.

Train Elements

Element Description
CarrierCode The code of the train carrier.
CarrierName The name of the train carrier.
TrainNumber The train number.
ArrivalDateTime The train arrival time. Only provided for the PickupLocation element. Format: 2015-05-19T18:00:00
DepartureDateTime The train departure time. Only provided for the DropoffLocation element. Format: 2015-05-19T18:00:00

Response

The supplier responds to the Limo Search request by returning the details of an available reservation that matches the search criteria.

Content Types

application/xml

Content Body

The response will include a CC_LimoSearchReply parent element, with the following child elements:

Error: The error information, if an error occurred. Required. This parent element contains the following child elements:

Error Elements

Element Description
ErrorCode The code for the error. Will contain one of the following values:
100: Pickup/dropoff location related error
200: Pickup/dropoff time related error
300: Other request parameters related error
400: Credential related error
500: No rate/service available
900: Unknown error
ErrorSource The source of the error.
ErrorDescription The additional error information.

RequestData: This parent element contains a copy of the original request data. Only the ServiceType, PickupLocation, DropoffLocation, and StartDateTime elements are required.

Limos: This parent element contains a Limo child element with the available reservation information. Refer to the Limo Elements table for the details of the child elements of the Limo element.

Limo Elements

RateInfo: The rate information for the limo. Refer to the Rate Information Elements table for more information. Required.

Vehicle: The type of vehicle. Required. This parent element contains the following child elements:

VehicleType: One of the following values:

100: Sedan
200: Limo
250: Stretch Limo
300: SUV
350: Stretch SUV
400: Van
450: Mini-Bus
500: Motor Coach
600: Shuttle
700: Trolley
800: Carriage
900: Any

Description: The detailed description of the vehicle.

MaxPassengers: The maximum number of passengers allowed in the vehicle. Must be greater than zero.

VehicleID: Information to identify the specific vehicle.

Vendor: The reservation vendor. Required. This parent element contains the following child elements:

Vendor Elements

Element Description
VendorCode The vendor code for the vendor.
VendorName The vendor's name.
PhoneNumber The vendor's phone number.

AcceptedFops: The accepted forms of payment. Required. This parent element contains the FormOfPayment child element. The FormOfPayment element contains the allowed forms of payment. The possible child elements are:

FormOfPayment Elements

Element Description
CreditCard This element will appear if the Credit Card form of payment is accepted. Contains the Type child element with one of the following values: AX - American Express, CA - Master Card, VI - Visa, DS - Discover Card, DC - Diners Club
Cash This element will appear if the Cash form of payment is accepted.
Check This element will appear if the Check form of payment is accepted.
DirectBilling This element will appear if the Direct Billing form of payment is accepted.

Rate Information Elements

Element Required? Description
RateID Y The rate identifier.
Rate Y The BasePrice + ServiceCharge + SurCharge + Tax
RateTypeCode Y The code for the rate type. Will be one of the following options:
F: Flat rate
H: Hourly
E: Estimated amount
N: Currently not available
CategoryCode N Extra information that will be passed back during sell request to help identify the rate.
Currency Y The 3-letter ISO 4217 currency code for the rate amount.
NoRateText N Explanation of rate type. Provided if RateTypeCode = N
MinHours N The minimum number of hours for the reservation.
DiscountType N The type of discount applied.
BasePrice N The reservation price without taxes, surcharges or service charges.
ServiceCharge N The service charge for the reservation.
SurCharge N This element contains the desc attribute, with text describing the reason for the surcharge. Example: <SurCharge desc="fuel">
Tax N The reservation tax.
ExtraPickupCharge N Any additional fees for the pickup service.
ExtraDropoffCharge N Any additional fees for the drop off service.
OptionalExtraStopCharge N The charge for any additional stops.
OptionalExtraTimeCharge N The charge for each additional hour.

Examples

XML Example Request

POST /concur/groundtransportation HTTPS/1.1
Host: example.com
Authorization: Basic ...
Content-Type: application/xml
Content-Length: {length of content body}

<CC_LimoSearchRequest>
    <ServiceType>110</ServiceType>
    <ClassOfService>100</ClassOfService>
    <PickupLocation>
        <LocationType>100</LocationType>
        <Airport>
            <AirportCode />
        </Airport>
        <Address>209 Madison St., Suite 400</Address>
        <City>Alexandria</City>
        <State>VA</State>
        <Country>US</Country>
        <PostalCode>22314</PostalCode>
    </PickupLocation>
    <DropoffLocation>
        <LocationType>200</LocationType>
        <Airport>
            <AirportCode>DCA</AirportCode>
        </Airport>
        <Address />
        <City />
        <State />
        <Country />
        <PostalCode />
    </DropoffLocation>
    <StartDateTime>2012-03-14T09:00</StartDateTime>
    <EndDateTime />
    <PickupInstructions />
    <DropoffInstructions />
    <LanguageCode>en-us</LanguageCode>
    <Currency>USD</Currency>
    <NumPassengers>1</NumPassengers>
    <DiscountCode />
    <VehicleType>100</VehicleType>
</CC_LimoSearchRequest>

XML Example of Successful Response

HTTPS/1.1 200 OK
Content-Type: application/xml
Content-Length: {length of content body}

<CC_LimoSearchReply size="1396" elaspedMs="782">
    <Error>
        <ErrorCode />
        <ErrorSource />
        <ErrorDescription />
    </Error>
    <RequestData>
        <ServiceType>110</ServiceType>
        <ClassOfService>100</ClassOfService>
        <PickupLocation>
            <Airport />
            <Address>209 Madison St. #400</Address>
            <City>Alexandria</City>
            <State>VA</State>
            <Country>US</Country>
            <PostalCode>22314</PostalCode>
        </PickupLocation>
        <DropoffLocation>
            <Airport>DCA</Airport>
            <Address />
            <City />
            <State />
            <Country />
            <PostalCode />
        </DropoffLocation>
        <StartDateTime>2012-02-19T09:00:00</StartDateTime>
        <EndDateTime />
        <PickupInstructions />
        <DropoffInstructions />
        <Country>US</Country>
        <NumPassengers>1</NumPassengers>
        <VehicleType>100</VehicleType>
    </RequestData>
    <Limos>
        <Limo>
            <RateInfo>
                <RateID>1</RateID>
                <Rate>42.50</Rate>
                <RateTypeCode>100</RateTypeCode>
                <CategoryCode />
                <MinHours />
                <Currency>USD</Currency>
                <NoRateText />
                <DiscountType />
                <BasePrice>35.00</BasePrice>
                <ServiceCharge>5.00</ServiceCharge>
                <SurChange desc="fuel">1.00</SurChange>
                <Tax>1.50</Tax>
                <ExtraPickupCharge />
                <ExtraDropoffCharge />
                <OptionalExtraStopCharge />
                <OptionalExtraTimeCharge />
                <Message>Ordinary Limo</Message>
            </RateInfo>
            <Vehicle>
                <VehicleType>Sedan</VehicleType>
                <Description>This is a Sedan.</Description>
                <MaxPassengers>1</MaxPassengers>
                <VehicleID>12</VehicleID>
            </Vehicle>
            <Vendor>
                <VendorCode>LML</VendorCode>
                <VendorName>LimoVendor</VendorName>
                <PhoneNumber>4354654654</PhoneNumber>
            </Vendor>
            <AcceptedFops>
                <FormOfPayment>
                    <CreditCard>
                        <Type>VI</Type>
                    </CreditCard>
                </FormOfPayment>
            </AcceptedFops>
        </Limo>
    </Limos>
</CC_LimoSearchReply>

Direct Connect - Ground Transportation - Post a transportation search

A post transportation search request is sent when the Travel user searches for ground transportation.

Request

URI

The Ground Transportation direct connect sends the relevant information to a URI that the travel supplier maintains. The standard location is:

https://{servername}/concur/groundtransportation

The URI is configured by the supplier when registering the partner application.

Headers

Accept Header

application/xml

Authorization Header

Authorization header with OAuth credentials.

Request Body

The request will contain a CC_LimoSearchRequest parent element, containing the following child elements.

ServiceType: The type of service requested. Will contain one of the following values:

100: Point to point
110: One way to airport
111: One way from airport
120: One way to train station
121: One way from train station
200: Hourly
300: Airport to airport

ClassOfService: The requested service class. Will contain one of the following values:

100: Normal
200: High
300: Highest

If this value is not provided by the user, it will default to 100.

PickupLocation: The pick up location. This parent element contains the following child elements:

PickupLocation Elements

Element Description
LocationType One of the following: 100 - Address, 200 - Airport, 300 - Train station.
Airport Refer to the Airport Elements table. Provided if the LocationType = 200.
TrainStation Refer to the Train Station Elements table. Provided if the LocationType = 300.
Address The street address of the location. Provided if the LocationType = 100.
City The location city.
State The location state. Preferably 2 characters, max 10 characters.
Country The location's 2 character ISO 3166-1 alpha-2 country code. Example: US
PostalCode The location postal code.
ExtraNotes Additional notes about the location. Example: Ring doorbell, Holiday Inn, etc.

DropoffLocation: The drop off location. This parent element contains the following child elements:

DropoffLocation Elements

Element Description
LocationType One of the following: 100 - Address, 200 - Airport, 300 - Train station.
Airport Refer to the Airport Elements table. Provided if the LocationType = 200.
TrainStation Refer to the Train Station Elements table. Provided if the LocationType = 300.
Address The street address of the location. Provided if the LocationType = 100.
City The location city.
State The location state. Preferably 2 characters, max 10 characters.
Country The location's 2 character ISO 3166-1 alpha-2 country code. Example: US
PostalCode The location postal code.
ExtraNotes Additional notes about the location. Example: Apartment building, gravel driveway, etc.

StartDateTime: The time, in GMT, that the reservation must begin. Format: 2015-05-19T18:00:00

EndDateTime: The time, in GMT that the reservation will end. Provided for hourly reservations. Format: 2015-05-19T18:00:00

PickupInstructions: Additional instructions about the pick up request.

DropoffInstructions: Additional instructions about the drop off request.

LanguageCode: The language of the traveler. Will be one of the following options:

en: English
en-us: English (US)
en-gb: English (UK)
fr: French
fr-ca: French (Canadian)
de: German
pt: Portuguese
es: Spanish
nl: Dutch
it: Italian
ja: Japanese
pl: Polish
pt-br: Portuguese (Brazilian)
ru: Russian
hu: Hungarian
ko: Korean
sv: Swedish
zh-cn: Chinese
zh-tw: Traditional Chinese

Currency: The 3-letter ISO 4217 currency code for the reservation amount.

NumPassengers: The number of passengers.

VehicleType: The type of vehicle requested. Will be one of the following options:

100: Sedan
200: Limo
201: Stretch Limo
300: SUV
301: Stretch SUV
400: Van
401: Mini-Bus
402: Bus
500: Motor Coach
501: Antique/Classic
502: Trolley
503: Carriage
600: Shuttle
900: Any

DiscountCode: The discount code information. This parent element contains the following child elements:

DiscountCode Elements

Element Description
CorporateID The user's corporate ID.
VendorCode The user's vendor code.
DiscountNumber The user's discount number.

Airport Elements

AirportCode: The IATA Code for the airport.

Flight: The flight information. This parent element contains the following child elements:

Flight Elements

Element Description
CarrierCode The airline code.
FlightNumber The flight number.
ArrivalDateTime The flight arrival time. Only provided for the PickupLocation element. Format: 2015-05-19T18:00:00
DepartureDateTime The flight departure time. Only provided for the DropoffLocation element. Format: 2015-05-19T18:00:00

Train Station Elements

Element Description
StationCode The station code.
StationName The name of the station.
City The city the station is located in.
State The state the station is located in. Preferably 2 characters, max 10 characters.
Train The train information. This parent element contains the following child elements.

Train Elements

Element Description
CarrierCode The code of the train carrier.
CarrierName The name of the train carrier.
TrainNumber The train number.
ArrivalDateTime The train arrival time. Only provided for the PickupLocation element. Format: 2015-05-19T18:00:00
DepartureDateTime The train departure time. Only provided for the DropoffLocation element. Format: 2015-05-19T18:00:00

Response

The supplier responds to the Limo Search request by returning the details of an available reservation that matches the search criteria.

Content Types

application/xml

Content Body

The response will include a CC_LimoSearchReply parent element, with the following child elements:

Error: The error information, if an error occurred. Required. This parent element contains the following child elements:

Error Elements

Element Description
ErrorCode The code for the error. Will contain one of the following values:
100: Pickup/dropoff location related error
200: Pickup/dropoff time related error
300: Other request parameters related error
400: Credential related error
500: No rate/service available
900: Unknown error
ErrorSource The source of the error.
ErrorDescription The additional error information.

RequestData: This parent element contains a copy of the original request data. Only the ServiceType, PickupLocation, DropoffLocation, and StartDateTime elements are required.

Limos: This parent element contains a Limo child element with the available reservation information. Refer to the Limo Elements table for the details of the child elements of the Limo element.

Limo Elements

RateInfo: The rate information for the limo. Refer to the Rate Information Elements table for more information. Required.

Vehicle: The type of vehicle. Required. This parent element contains the following child elements:

VehicleType: One of the following values:

100: Sedan
200: Limo
250: Stretch Limo
300: SUV
350: Stretch SUV
400: Van
450: Mini-Bus
500: Motor Coach
600: Shuttle
700: Trolley
800: Carriage
900: Any

Description: The detailed description of the vehicle.

MaxPassengers: The maximum number of passengers allowed in the vehicle. Must be greater than zero.

VehicleID: Information to identify the specific vehicle.

Vendor: The reservation vendor. Required. This parent element contains the following child elements:

Vendor Elements

Element Description
VendorCode The vendor code for the vendor.
VendorName The vendor's name.
PhoneNumber The vendor's phone number.

AcceptedFops: The accepted forms of payment. Required. This parent element contains the FormOfPayment child element. The FormOfPayment element contains the allowed forms of payment. The possible child elements are:

FormOfPayment Elements

Element Description
CreditCard This element will appear if the Credit Card form of payment is accepted. Contains the Type child element with one of the following values: AX - American Express, CA - Master Card, VI - Visa, DS - Discover Card, DC - Diners Club
Cash This element will appear if the Cash form of payment is accepted.
Check This element will appear if the Check form of payment is accepted.
DirectBilling This element will appear if the Direct Billing form of payment is accepted.

Rate Information Elements

Element Required? Description
RateID Y The rate identifier.
Rate Y The BasePrice + ServiceCharge + SurCharge + Tax
RateTypeCode Y The code for the rate type. Will be one of the following options:
F: Flat rate
H: Hourly
E: Estimated amount
N: Currently not available
CategoryCode N Extra information that will be passed back during sell request to help identify the rate.
Currency Y The 3-letter ISO 4217 currency code for the rate amount.
NoRateText N Explanation of rate type. Provided if RateTypeCode = N
MinHours N The minimum number of hours for the reservation.
DiscountType N The type of discount applied.
BasePrice N The reservation price without taxes, surcharges or service charges.
ServiceCharge N The service charge for the reservation.
SurCharge N This element contains the desc attribute, with text describing the reason for the surcharge. Example: <SurCharge desc="fuel">
Tax N The reservation tax.
ExtraPickupCharge N Any additional fees for the pickup service.
ExtraDropoffCharge N Any additional fees for the drop off service.
OptionalExtraStopCharge N The charge for any additional stops.
OptionalExtraTimeCharge N The charge for each additional hour.

Examples

XML Example Request

POST /concur/groundtransportation HTTPS/1.1
Host: example.com
Authorization: Basic ...
Content-Type: application/xml
Content-Length: {length of content body}

<CC_LimoSearchRequest>
    <ServiceType>110</ServiceType>
    <ClassOfService>100</ClassOfService>
    <PickupLocation>
        <LocationType>100</LocationType>
        <Airport>
            <AirportCode />
        </Airport>
        <Address>209 Madison St., Suite 400</Address>
        <City>Alexandria</City>
        <State>VA</State>
        <Country>US</Country>
        <PostalCode>22314</PostalCode>
    </PickupLocation>
    <DropoffLocation>
        <LocationType>200</LocationType>
        <Airport>
            <AirportCode>DCA</AirportCode>
        </Airport>
        <Address />
        <City />
        <State />
        <Country />
        <PostalCode />
    </DropoffLocation>
    <StartDateTime>2012-03-14T09:00</StartDateTime>
    <EndDateTime />
    <PickupInstructions />
    <DropoffInstructions />
    <LanguageCode>en-us</LanguageCode>
    <Currency>USD</Currency>
    <NumPassengers>1</NumPassengers>
    <DiscountCode />
    <VehicleType>100</VehicleType>
</CC_LimoSearchRequest>

XML Example of Successful Response

HTTPS/1.1 200 OK
Content-Type: application/xml
Content-Length: {length of content body}

<CC_LimoSearchReply size="1396" elaspedMs="782">
    <Error>
        <ErrorCode />
        <ErrorSource />
        <ErrorDescription />
    </Error>
    <RequestData>
        <ServiceType>110</ServiceType>
        <ClassOfService>100</ClassOfService>
        <PickupLocation>
            <Airport />
            <Address>209 Madison St. #400</Address>
            <City>Alexandria</City>
            <State>VA</State>
            <Country>US</Country>
            <PostalCode>22314</PostalCode>
        </PickupLocation>
        <DropoffLocation>
            <Airport>DCA</Airport>
            <Address />
            <City />
            <State />
            <Country />
            <PostalCode />
        </DropoffLocation>
        <StartDateTime>2012-02-19T09:00:00</StartDateTime>
        <EndDateTime />
        <PickupInstructions />
        <DropoffInstructions />
        <Country>US</Country>
        <NumPassengers>1</NumPassengers>
        <VehicleType>100</VehicleType>
    </RequestData>
    <Limos>
        <Limo>
            <RateInfo>
                <RateID>1</RateID>
                <Rate>42.50</Rate>
                <RateTypeCode>100</RateTypeCode>
                <CategoryCode />
                <MinHours />
                <Currency>USD</Currency>
                <NoRateText />
                <DiscountType />
                <BasePrice>35.00</BasePrice>
                <ServiceCharge>5.00</ServiceCharge>
                <SurChange desc="fuel">1.00</SurChange>
                <Tax>1.50</Tax>
                <ExtraPickupCharge />
                <ExtraDropoffCharge />
                <OptionalExtraStopCharge />
                <OptionalExtraTimeCharge />
                <Message>Ordinary Limo</Message>
            </RateInfo>
            <Vehicle>
                <VehicleType>Sedan</VehicleType>
                <Description>This is a Sedan.</Description>
                <MaxPassengers>1</MaxPassengers>
                <VehicleID>12</VehicleID>
            </Vehicle>
            <Vendor>
                <VendorCode>LML</VendorCode>
                <VendorName>LimoVendor</VendorName>
                <PhoneNumber>4354654654</PhoneNumber>
            </Vendor>
            <AcceptedFops>
                <FormOfPayment>
                    <CreditCard>
                        <Type>VI</Type>
                    </CreditCard>
                </FormOfPayment>
            </AcceptedFops>
        </Limo>
    </Limos>
</CC_LimoSearchReply>

Direct Connect - Ground Transportation - Update reservation with supplier

This request is sent when the Travel user updates an existing ground transportation reservation.

Request

URI

The Ground Transportation direct connect sends the relevant information to a URI that the travel supplier maintains. The standard location is:

https://{servername}/concur/groundtransportation

The URI is configured by the supplier when registering the partner application.

Headers

Accept Header

application/xml

Authorization Header

Authentication header with Base64 encoded basic authentication credentials (login ID and password) is required. The basic authentication credentials are established during the application review process.

Authorization: Basic {Base64 encoded LoginID:Password}

Request Body

The request will contain a CC_LimoUpdateRequest parent element, containing the following child elements:

Element Required? Description
ReservationID The unique identifier for the reservation.
CorporateClient The corporate client the booking is on behalf of. This parent element contains a CompanyCode child element containing the code for the company of the client.
Booker The user booking the reservation. For information about the child elements of this parent element, see the Booker elements table below.
PrimaryPassenger The passenger contact name for the reservation. For information about the child elements of this parent element, see the PrimaryPassenger elements table below.
ServiceType The type of service requested. Will contain one of the following values:
100: Point to point
110: One way to airport
111: One way from airport
120: One way to train station
121: One way from train station
200: Hourly
300: Airport to airport
ClassOfService The requested service class. Will contain one of the following values:
100: Normal
200: High
300: Highest

If this value is not provided by the user, it will default to 100.
PickupLocation The pick up location. For information about the child elements of this parent element, see the PickupLocation elements table below.
DropoffLocation The drop off location. For information about the child elements of this parent element, see the DropoffLocation elements table below.
StartDateTime The time, in GMT, that the reservation must begin. Format: 2015-05-19T18:00:00
EndDateTime The time, in GMT that the reservation will end. Provided for hourly reservations. Format: 2015-05-19T18:00:00
PickupInstructions Additional instructions about the pick up request.
DropoffInstructions Additional instructions about the drop off request.
LanguageCode The language of the traveler. Will be one of the following options:
en: English
en-us: English (US)
en-gb: English (UK)
fr: French
fr-ca: French (Canadian)
de: German
pt: Portuguese
es: Spanish
nl: Dutch
it: Italian
ja: Japanese
pl: Polish
pt-br: Portuguese (Brazilian)
ru: Russian
hu: Hungarian
ko: Korean
sv: Swedish
zh-cn: Chinese
zh-tw: Traditional Chinese
Currency The 3-letter ISO 4217 currency code for the reservation amount.
NumPassengers The number of passengers.
DiscountCode The discount code information. For information about the child elements of this parent element, see the DiscountCode elements table below.
FormOfPayment The form of payment for the reservation. For information about the child elements of this parent element, see the FormOfPayment elements table below.
AccountingInfo The accounting information for the reservation. This parent element contains one or more AccountingField elements: AccountingField1 through AccountingField5. These fields contain detailed accounting information.
RequestedDriver The name of the requested driver, if available.
SpecialServiceRequest The details of the special service request, if available.
PickupServiceArrangement The details of the pickup arrangement, if available.
DropoffServiceArrangement The details of the dropoff arrangement, if available.
ExtraStopArrangement The details of the extra stop arrangement, if available.

Booker Elements

Element Description
UserID The user's SAP Concur user ID.
EmailAddress The user's email address.
Phone The user's contact number.

PrimaryPassenger Elements

Element Description
FirstName The contact's first name.
LastName The contact's last name.
Phone The contact's phone number.
Phone2 The contact's backup phone number.
CellPhone The contact's cell phone number.
EmailAddress The contact's email address.

PickupLocation Elements

Element Description
LocationType One of the following: 100 - Address, 200 - Airport, 300 - Train station.
Airport Refer to the Airport elements table. Provided if the LocationType = 200.
TrainStation Refer to the Train Station elements table. Provided if the LocationType = 300.
Address The street address of the location. Provided if the LocationType = 100.
City The location city.
State The location state. Preferably 2 characters, max 10 characters.
Country The location's 2 character ISO 3166-1 alpha-2 country code. Example: US
PostalCode The location postal code.
ExtraNotes Additional notes about the location. Example: Ring doorbell, Holiday Inn, etc.

DropoffLocation Elements

Element Description
LocationType One of the following: 100 - Address, 200 - Airport, 300 - Train station, 400 - As directed.
Airport Refer to the Airport elements table. Provided if the LocationType = 200.
TrainStation Refer to the Train Station elements table. Provided if the LocationType = 300.
Address The street address of the location. Provided if the LocationType = 100.
City The location city.
State The location state. Preferably 2 characters, max 10 characters.
Country The location's 2 character ISO 3166-1 alpha-2 country code. Example: US
PostalCode The location postal code.
ExtraNotes Additional notes about the location. Example: Apartment Building, gravel driveway, etc.

DiscountCode Elements

Element Name Description
CorporateID The user's corporate ID.
VendorCode The user's vendor code.
DiscountNumber The user's discount number.

FormOfPayment Elements

Element Description
CreditCard If present, the passenger will pay with credit card. Refer to the Credit Card Elements table for the child elements.
Cash If present, the passenger will pay cash.
Check If present, the passenger will pay with a check.
DirectBilling If present, the passenger will pay through direct billing.

Airport Elements

Element Name Description
AirportCode The IATA code for the airport.
Flight The flight information. For information about the child elements of this parent element, see the Flight elements table below.

Flight Elements

Element Name Description
CarrierCode The airline code.
FlightNumber The flight number.
ArrivalDateTime The flight arrival time. Only provided for the PickupLocation element. Format: 2015-05-19T18:00:00
DepartureDateTime The flight departure time. Only provided for the DropoffLocation element. Format: 2015-05-19T18:00:00

Train Station Elements

Element Name Required/Optional Data Type Description
StationCode The station code.
StationName The name of the station.
City The city the station is located in.
State The state the station is located in. Preferably 2 characters, max 10 characters.
Train The train information. For information about the child elements of this parent element, see the Train elements table below.

Train Elements

Element Name Description
CarrierCode The code of the train carrier.
CarrierName The name of the train carrier.
TrainNumber The train number.
ArrivalDateTime The train arrival time. Only provided for the PickupLocation element. Format: 2015-05-19T18:00:00
DepartureDateTime The train departure time. Only provided for the DropoffLocation element. Format: 2015-05-19T18:00:00

Credit Card Elements

Element Name Description
Type The card type.
Number The card number.
Expiration The card expiration date. Format: 2013-02-19
Name The name on the card.
Address The street information of the billing address of the car.
City The city of the billing address of the car.
State The state of the billing address of the car.
Country The country of the billing address of the car.
PostalCode The postal code of the billing address of the car.

Response

The supplier responds to the update request with the reservation details.

Content Types

application/xml

Response Schema

The response will include a CC_LimoUpdateReply parent element, with the following child elements:

Element Required? Description
Error Y The error information, if an error occurred. For information about the child elements of this parent element, see the Error elements table below.
ReservationID N The identifier for the reservation.
Status N The status of the reservation. The value will be one of the following:
RB: Reservation Booked
RA: Reservation Accepted
RD: Reservation Declined
CB: Change Booked
CA: Change Accepted
CD: Change Declined
XB: Cancellation Requested
XA: Cancellation Accepted
XD: Cancellation Declined
RC: Reservation Closed
ConfNum N The confirmation number for the reservation.
CancelPolicy N The cancellation policy for the reservation.
CancelNum N The cancellation number for the reservation.
PrimaryPassenger Y The passenger contact name for the reservation. For information about the child elements of this parent element, see the PrimaryPassenger elements table above.
ServiceType Y The type of service requested. Will contain one of the following values:
100: Point to point
110: One way to airport
111: One way from airport
120: One way to train station
121: One way from train station
200: Hourly
300: Airport to airport
ClassOfService N The requested service class. Will contain one of the following values:
100: Normal
200: High
300: Highest

If this value is not provided by the user, it will default to 100.
PickupLocation Y The pick up location. For information about the child elements of this parent element, see the PickupLocation elements table above.
DropoffLocation Y The drop off location. For information about the child elements of this parent element, see the DropoffLocation elements table above.
StartDateTime Y The time, in GMT, that the reservation must begin. Format: 2015-05-19T18:00:00
EndDateTime N The time, in GMT that the reservation will end. Provided for hourly reservations. Format: 2015-05-19T18:00:00
PickupInstructions N Additional instructions about the pick up request.
DropoffInstructions N Additional instructions about the drop off request.
LanguageCode Y The language of the traveler. Will be one of the following options:
en: English
en-us: English (US)
en-gb: English (UK)
fr: French
fr-ca: French (Canadian)
de: German
pt: Portuguese
es: Spanish
nl: Dutch
it: Italian
ja: Japanese
pl: Polish
pt-br: Portuguese (Brazilian)
ru: Russian
hu: Hungarian
ko: Korean
sv: Swedish
zh-cn: Chinese
zh-tw: Traditional Chinese
Currency Y The 3-letter ISO 4217 currency code for the reservation amount.
NumPassengers N The number of passengers.
RequestedDriver N The name of the requested driver, if available.
SpecialServiceRequest N The details of the special service request, if available.
PickupServiceArrangement N The details of the pickup arrangement, if available.
DropoffServiceArrangement N The details of the dropoff arrangement, if available.
ExtraStopArrangement N The details of the extra stop arrangement, if available.
RateInfo Y The booked rate details. Refer to the Rate Information elements table below for more information.
Vehicle Y The vehicle details. For information about the child elements of this parent element, see the Vehicle elements table below.
Vendor Y The reservation vendor. For information about the child elements of this parent element, see the Vendor elements table below.
FormOfPayment Y The form of payment for the reservation. For information about the child elements of this parent element, see the FormOfPayment elements table below.
RateDisclaimer N Disclaimer text about the rate.
ProviderFeedback N Any additional feedback from the supplier.
AccountingInfo N The accounting information for the reservation. This parent element contains one or more AccountingField elements: AccountingField1 through AccountingField5. These fields contain detailed accounting information.

Error Elements

Element Description
ErrorCode The code for the error. Will contain one of the following values:
100: Pickup/dropoff location related error
200: Pickup/dropoff time related error
300: Other request parameters related error
400: Credential related error
500: No rate/service available
600: FOP related error
900: Unknown error
ErrorSource The source of the error.
ErrorDescription The additional error information.

Vehicle Elements

Element Description
VehicleType One of the following values:
100: Sedan
200: Limo
250: Stretch Limo
300: SUV
350: Stretch SUV
400: Van
450: Mini-Bus
500: Motor Coach
600: Shuttle
700: Trolley
800: Carriage
900: Any
Description The vehicle description.
MaxPassengers The maximum number of passengers for the car. Must be greater than zero.
VehicleID Information to identify the specific vehicle.

Rate Information Elements

Element Name Required? Data Type Description
RateID Y The rate identifier.
Rate Y The BasePrice + ServiceCharge + SurCharge + Tax
RateTypeCode Y The code for the rate type. Will be one of the following options:
F: Flat rate
H: Hourly
E: Estimated amount
N: Currently not available
CategoryCode N Extra information that will be passed back during sell request to help identify the rate.
Currency Y The 3-letter ISO 4217 currency code for the rate amount.
NoRateText N Explanation of rate type. Provided if RateTypeCode = N
MinHours N The minimum number of hours for the reservation.
DiscountType N The type of discount applied.
BasePrice N The reservation price without taxes, surcharges or service charges.
ServiceCharge N The service charge for the reservation.
SurCharge N This element contains the desc attribute, with text describing the reason for the surcharge. Example: <SurCharge desc="fuel">
Tax N The reservation tax.
ExtraPickupCharge N Any additional fees for the pickup service.
ExtraDropoffCharge N Any additional fees for the drop off service.
OptionalExtraStopCharge N The charge for any additional stops.
OptionalExtraTimeCharge N The charge for each additional hour.

Vendor Elements

Element Description
VendorCode The vendor code for the vendor.
VendorName The vendor's name.
PhoneNumber The vendor's phone number.

FormOfPayment Elements

Element Description
CreditCard If present, the passenger will pay with credit card. Refer to the Reply Credit Card elements table for the child elements.
Cash If present, the passenger will pay cash.
Check If present, the passenger will pay with a check.
DirectBilling If present, the passenger will pay through direct billing.

Airport Elements

Element Name Description
AirportCode The IATA code for the airport.
Flight The flight information. For information about the child elements of this parent element, see the Flight elements table below.

Flight Elements

Element Name Description
CarrierCode The airline code.
FlightNumber The flight number.
ArrivalDateTime The flight arrival time. Only provided for the PickupLocation element. Format: 2015-05-19T18:00:00
DepartureDateTime The flight departure time. Only provided for the DropoffLocation element. Format: 2015-05-19T18:00:00

Train Station Elements

Element Name Required/Optional Data Type Description
StationCode The station code.
StationName The name of the station.
City The city the station is located in.
State The state the station is located in. Preferably 2 characters, max 10 characters.
Train The train information. For information about the child elements of this parent element, see the Train elements table below.

Train Elements

Element Name Description
CarrierCode The code of the train carrier.
CarrierName The name of the train carrier.
TrainNumber The train number.
ArrivalDateTime The train arrival time. Only provided for the PickupLocation element. Format: 2015-05-19T18:00:00
DepartureDateTime The train departure time. Only provided for the DropoffLocation element. Format: 2015-05-19T18:00:00

Reply Credit Card Elements

Element Name Required? Description
Type The card type.
Number The card number.
Expiration The card expiration date. Format: 2013-02-19

Examples

XML Example Request

POST /concur/groundtransportation HTTPS/1.1
Host: example.com
Authorization: Basic ...
Content-Type: application/xml
Content-Length: {length of content body}

<CC_LimoUpdateRequest>
    <ReservationID>1234</ReservationID>
    <CorporateClient>
        <CompanyCode>339</CompanyCode>
    </CorporateClient>
    <Booker>
        <UserID>55414</UserID>
        <EmailAddress>cmiller@example.com</EmailAddress>
        <Phone>5551234567</Phone>
    </Booker>
    <PrimaryPassenger>
        <FirstName>Chris</FirstName>
        <LastName>Miller</LastName>
        <Phone>5551234567</Phone>
        <Phone2>5551234568</Phone2>
        <CellPhone>5551234555</CellPhone>
        <EmailAddress>cmiller@example.com</EmailAddress>
    </PrimaryPassenger>
    <ServiceType>110</ServiceType>
    <ClassOfService />
    <PickupLocation>
        <LocationType>100</LocationType>
        <Airport>
            <AirportCode />
            <Flight>
                <CarrierCode />
                <FlightNumber />
                <ArrivalDateTime />
            </Flight>
        </Airport>
        <TrainStation>
            <StationCode />
            <StationName />
            <City />
            <State />
            <Train>
                <CarrierCode />
                <CarrierName />
                <TrainNumber />
                <ArrivalDateTime />
            </Train>
        </TrainStation>
        <Address>209 Madison St</Address>
        <City>Alexandria</City>
        <State>VA</State>
        <Country>US</Country>
        <PostalCode>22314</PostalCode>
        <ExtraNotes />
    </PickupLocation>
    <DropoffLocation>
        <LocationType>200</LocationType>
        <Airport>
            <AirportCode>DCA</AirportCode>
            <Flight>
                <CarrierCode>UA</CarrierCode>
                <FlightNumber>333</FlightNumber>
                <DepartureDateTime>2012-02-19T11:29:00</DepartureDateTime>
            </Flight>
        </Airport>
        <TrainStation>
            <StationCode />
            <StationName />
            <City />
            <State />
            <Train>
                <CarrierCode />
                <CarrierName />
                <TrainNumber />
                <DepartureDateTime />
            </Train>
        </TrainStation>
        <Address />
        <City />
        <State />
        <Country />
        <PostalCode />
        <ExtraNotes />
    </DropoffLocation>
    <StartDateTime>2012-02-19T09:00:00</StartDateTime>
    <EndDateTime />
    <PickupInstructions>pick me up</PickupInstructions>
    <DropoffInstructions>None</DropoffInstructions>
    <LanguageCode>en-us</LanguageCode>
    <Currency>USD</Currency>
    <NumPassengers>1</NumPassengers>
    <DiscountCode>
        <CorporateID />
        <VendorCode />
        <DiscountNumber />
    </DiscountCode>
    <FormOfPayment>
        <Cash />
        <Check />
        <DirectBilling />
        <CreditCard>
            <Type>VI</Type>
            <Number>XXXXXXXXXXXX1111</Number>
            <Expiration>2013-02-19</Expiration>
        </CreditCard>
    </FormOfPayment>
    <AccountingInfo>
        <AccountingField1>715</AccountingField1>
        <AccountingField2>temp@outtask.com</AccountingField2>
        <AccountingField3>11</AccountingField3>
        <AccountingField4>Development</AccountingField4>
        <AccountingField5/>
    </AccountingInfo>
    <RequestedDriver />
    <SpecialServiceRequest />
    <PickupServiceArrangement />
    <DropoffServiceArrangement />
    <ExtraStopArrangement />
</CC_LimoUpdateRequest>

XML Example of Successful Response

HTTPS/1.1 200 OK
Content-Type: application/xml
Content-Length: {length of content body}

<CC_LimoUpdateReply>
    <Error>
        <ErrorCode />
        <ErrorSource />
        <ErrorDescription />
    </Error>
    <ReservationID>1234</ReservationID>
    <Status>RB</Status>
    <ConfNum/>
    <CancelPolicy />
    <CancelNum/>
    <PrimaryPassenger>
        <FirstName>Chris</FirstName>
        <LastName>Miller</LastName>
        <Phone>5551234567</Phone>
        <Phone2>5551234568</Phone2>
        <CellPhone>5551234555</CellPhone>
        <EmailAddress>cmiller@example.com</EmailAddress>
    </PrimaryPassenger>
    <ServiceType>110</ServiceType>
    <ClassOfService />
    <PickupLocation>
        <LocationType>100</LocationType>
        <Airport>
            <AirportCode />
            <Flight>
                <CarrierCode />
                <FlightNumber />
                <ArrivalDateTime />
            </Flight>
        </Airport>
        <TrainStation>
            <StationCode />
            <StationName />
            <City />
            <State />
            <Train>
                <CarrierCode />
                <CarrierName />
                <TrainNumber />
            </Train>
        </TrainStation>
        <Address>209 Madison St #400</Address>
        <City>Alexandria</City>
        <State>VA</State>
        <Country>US</Country>
        <PostalCode>22314</PostalCode>
        <ExtraNotes />
    </PickupLocation>
    <DropoffLocation>
        <LocationType>200</LocationType>
        <Airport>
            <AirportCode>DCA</AirportCode>
            <Flight>
                <CarrierCode>UA</CarrierCode>
                <FlightNumber>333</FlightNumber>
                <DepartureDateTime>2012-02-19T11:29:00</DepartureDateTime>
            </Flight>
        </Airport>
        <TrainStation>
            <StationCode />
            <StationName />
            <City />
            <State />
            <Train>
                <CarrierCode />
                <CarrierName />
                <TrainNumber />
                <DepartureDateTime />
            </Train>
        </TrainStation>
        <Address />
        <City />
        <State />
        <Country />
        <PostalCode />
        <ExtraNotes />
    </DropoffLocation>
    <StartDateTime>2012-02-19T09:00:00</StartDateTime>
    <EndDateTime />
    <PickupInstructions>pick me up</PickupInstructions>
    <DropoffInstructions>None</DropoffInstructions>
    <LanguageCode>en-us</LanguageCode>
    <Currency>USD</Currency>
    <NumPassengers>1</NumPassengers>
    <RequestedDriver />
    <SpecialServiceRequest />
    <PickupServiceArrangement />
    <DropoffServiceArrangement />
    <ExtraStopArrangement />
    <RateInfo>
        <RateID>5</RateID>
        <Rate>42.50</Rate>
        <RateTypeCode>E</RateTypeCode>
        <CategoryCode />
        <MinHours />
        <Currency>US</Currency>
        <NoRateText />
        <DiscountType />
        <BasePrice>35.00</BasePrice>
        <ServiceCharge>5.00</ServiceCharge>
        <SurCharge desc="fuel">1.00</SurCharge>
        <Tax>1.50</Tax>
        <ExtraPickupCharge />
        <ExtraDropoffCharge />
        <OptionalExtraStopCharge />
        <OptionalExtraTimeCharge />
        <Message />
    </RateInfo>
    <RateDisclaimer />
    <Vehicle>
        <VehicleType>100</VehicleType>
        <Description>This is a Sedan.</Description>
        <MaxPassengers>1</MaxPassengers>
        <VehicleID>12</VehicleID>
    </Vehicle>
    <Vendor>
        <VendorCode>LML</VendorCode>
        <VendorName>LimoVendor</VendorName>
        <PhoneNumber>4354654654</PhoneNumber>
    </Vendor>
    <ProviderFeedback />
    <FormOfPayment>
        <Cash />
        <Check />
        <DirectBilling />
        <CreditCard>
            <Type>VI</Type>
            <Number>XXXXXXXXXXXX1111</Number>
            <Expiration>2013-02-19</Expiration>
        </CreditCard>
    </FormOfPayment>
    <AccountingInfo>
        <AccountingField1>715</AccountingField1>
        <AccountingField2>temp@outtask.com</AccountingField2>
        <AccountingField3>11</AccountingField3>
        <AccountingField4>Development</AccountingField4>
        <AccountingField5/>
    </AccountingInfo>
</CC_LimoUpdateReply>

Direct Connect - Ground Transportation - Update reservation with Travel

This API has been deprecated.

Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.

Learn more in the API Lifecycle & Deprecation Policy.

This request is sent when the ground transportation service provider needs to send an update to the reservation to Travel.

Request

URI

https://app2.outtask.com/api/tws/v1.0/Limo/PostBack

Headers

Accept Header

application/xml

Authorization Header

Authorization header with OAuth credentials. Required. Refer to the OAuth documentation for more information.

Authorization: OAuth {OAuth access token associated with the account making the call with Web Services Administrator role}

Request Body

The request will contain a CC_LimoPostBackRequest parent element, containing the following child elements:

Element Required? Description
Error Y The error information, if an error occurred. For information about the child elements of this parent element, see the Error elements table below.
ReservationID N The identifier for the reservation.
Status N The status of the reservation. The value will be one of the following:
RB: Reservation Booked
RA: Reservation Accepted
RD: Reservation Declined
CB: Change Booked
CA: Change Accepted
CD: Change Declined
XB: Cancellation Requested
XA: Cancellation Accepted
XD: Cancellation Declined
RC: Reservation Closed
ConfNum N The confirmation number for the reservation.
CancelPolicy N The cancellation policy for the reservation.
CancelNum N The cancellation number for the reservation.
PrimaryPassenger Y The passenger contact name for the reservation. For information about the child elements of this parent element, see the PrimaryPassenger elements table below.
ServiceType Y The type of service requested. Will contain one of the following values:
100: Point to point
110: One way to airport
111: One way from airport
120: One way to train station
121: One way from train station
200: Hourly
300: Airport to airport
ClassOfService N The requested service class. Will contain one of the following values:
100: Normal
200: High
300: Highest

If this value is not provided by the user, it will default to 100.
PickupLocation Y The pick up location. For information about the child elements of this parent element, see the PickupLocation elements table below.
DropoffLocation Y The drop off location. For information about the child elements of this parent element, see the DropoffLocation elements table below.
StartDateTime Y The time, in GMT, that the reservation must begin. Format: 2015-05-19T18:00:00
EndDateTime N The time, in GMT that the reservation will end. Provided for hourly reservations. Format: 2015-05-19T18:00:00
PickupInstructions N Additional instructions about the pick up request.
DropoffInstructions N Additional instructions about the drop off request.
LanguageCode Y The language of the traveler. Will be one of the following options:
en: English
en-us: English (US)
en-gb: English (UK)
fr: French
fr-ca: French (Canadian)
de: German
pt: Portuguese
es: Spanish
nl: Dutch
it: Italian
ja: Japanese
pl: Polish
pt-br: Portuguese (Brazilian)
ru: Russian
hu: Hungarian
ko: Korean
sv: Swedish
zh-cn: Chinese
zh-tw: Traditional Chinese
Currency Y The 3-letter ISO 4217 currency code for the reservation amount.
NumPassengers N The number of passengers.
RequestedDriver N The name of the requested driver, if available.
SpecialServiceRequest N The details of the special service request, if available.
PickupServiceArrangement N The details of the pickup arrangement, if available.
DropoffServiceArrangement N The details of the dropoff arrangement, if available.
ExtraStopArrangement N The details of the extra stop arrangement, if available.
RateInfo Y The booked rate details. Refer to the Rate Information elements table for more information.
Vehicle Y The vehicle details. For information about the child elements of this parent element, see the Vehicle elements table below.
Vendor Y The reservation vendor. For information about the child elements of this parent element, see the Vendor elements table below.
FormOfPayment Y The form of payment for the reservation. For information about the child elements of this parent element, see the FormOfPayment elements table below.
RateDisclaimer N Disclaimer text about the rate.
ProviderFeedback N Any additional feedback from the supplier.
AccountingInfo N The accounting information for the reservation. This parent element contains one or more AccountingField elements: AccountingField1 through AccountingField5. These fields contain detailed accounting information.

Error Elements

Element Description
ErrorCode The code for the error. Will contain one of the following values:
100: Pickup/dropoff location related error
200: Pickup/dropoff time related error
300: Other request parameters related error
400: Credential related error
500: No rate/service available
600: FOP related error
900: Unknown error
ErrorSource The source of the error.
ErrorDescription The additional error information.

PrimaryPassenger Elements

Element Description
FirstName The contact's first name.
LastName The contact's last name.
Phone The contact's phone number.
Phone2 The contact's backup phone number.
CellPhone The contact's cell phone number.
EmailAddress The contact's email address.

PickupLocation Elements

Element Description
LocationType One of the following: 100 - Address, 200 - Airport, 300 - Train station.
Airport Refer to the Airport elements table. Provided if the LocationType = 200.
TrainStation Refer to the Train Station elements table. Provided if the LocationType = 300.
Address The street address of the location. Provided if the LocationType = 100.
City The location city.
State The location state. Preferably 2 characters, max 10 characters.
Country The location's 2 character ISO 3166-1 alpha-2 country code. Example: US
PostalCode The location postal code.
ExtraNotes Additional notes about the location. Example: Ring doorbell, Holiday Inn, etc.

DropoffLocation Elements

Element Description
LocationType One of the following: 100 - Address, 200 - Airport, 300 - Train station, 400 - As directed.
Airport Refer to the Airport elements table. Provided if the LocationType = 200.
TrainStation Refer to the Train Station elements table. Provided if the LocationType = 300.
Address The street address of the location. Provided if the LocationType = 100.
City The location city.
State The location state. Preferably 2 characters, max 10 characters.
Country The location's 2 character ISO 3166-1 alpha-2 country code. Example: US
PostalCode The location postal code.
ExtraNotes Additional notes about the location. Example: Apartment Building, gravel driveway, etc.

Vehicle Elements

Element Description
VehicleType One of the following values:
100: Sedan
200: Limo
250: Stretch Limo
300: SUV
350: Stretch SUV
400: Van
450: Mini-Bus
500: Motor Coach
600: Shuttle
700: Trolley
800: Carriage
900: Any
Description The vehicle description.
MaxPassengers The maximum number of passengers for the car. Must be greater than zero.
VehicleID Information to identify the specific vehicle.

Vendor Elements

Element Description
VendorCode The vendor code for the vendor.
VendorName The vendor's name.
PhoneNumber The vendor's phone number.

FormOfPayment Elements

Element Description
CreditCard If present, the passenger will pay with credit card. Refer to the Reply Credit Card elements table for the child elements.
Cash If present, the passenger will pay cash.
Check If present, the passenger will pay with a check.
DirectBilling If present, the passenger will pay through direct billing.

Airport Elements

Element Name Description
AirportCode The IATA code for the airport.
Flight The flight information. For information about the child elements of this parent element, see the Flight elements table below.

Flight Elements

Element Name Description
CarrierCode The airline code.
FlightNumber The flight number.
ArrivalDateTime The flight arrival time. Only provided for the PickupLocation element. Format: 2015-05-19T18:00:00
DepartureDateTime The flight departure time. Only provided for the DropoffLocation element. Format: 2015-05-19T18:00:00

Train Station Elements

Element Name Required/Optional Data Type Description
StationCode The station code.
StationName The name of the station.
City The city the station is located in.
State The state the station is located in. Preferably 2 characters, max 10 characters.
Train The train information. For information about the child elements of this parent element, see the Train elements table below.

Train Child Elements

Element Name Description
CarrierCode The code of the train carrier.
CarrierName The name of the train carrier.
TrainNumber The train number.
ArrivalDateTime The train arrival time. Only provided for the PickupLocation element. Format: 2015-05-19T18:00:00
DepartureDateTime The train departure time. Only provided for the DropoffLocation element. Format: 2015-05-19T18:00:00

Rate Information Elements

Element Name Required? Data Type Description
RateID Y The rate identifier.
Rate Y The BasePrice + ServiceCharge + SurCharge + Tax
RateTypeCode Y The code for the rate type. Will be one of the following options:
F: Flat rate
H: Hourly
E: Estimated amount
N: Currently not available
CategoryCode N Extra information that will be passed back during sell request to help identify the rate.
Currency Y The 3-letter ISO 4217 currency code for the rate amount.
NoRateText N Explanation of rate type. Provided if RateTypeCode = N
MinHours N The minimum number of hours for the reservation.
DiscountType N The type of discount applied.
BasePrice N The reservation price without taxes, surcharges or service charges.
ServiceCharge N The service charge for the reservation.
SurCharge N This element contains the desc attribute, with text describing the reason for the surcharge. Example: <SurCharge desc="fuel">
Tax N The reservation tax.
ExtraPickupCharge N Any additional fees for the pickup service.
ExtraDropoffCharge N Any additional fees for the drop off service.
OptionalExtraStopCharge N The charge for any additional stops.
OptionalExtraTimeCharge N The charge for each additional hour.

Credit Card Elements

Element Name Required? Data Type Description
Type Y The card type.
Number Y The card number.
Expiration Y The card expiration date. Format: 2013-02-19

XML Example Request

POST /api/tws/v1.0/Limo/PostBack HTTPS/1.1
Host: app2.outtask.com/
Authorization: Basic ...
Content-Type: application/xml
Content-Length: {length of content body}

<CC_LimoPostBackRequest>
    <Error>
        <ErrorCode />
        <ErrorSource />
        <ErrorDescription />
    </Error>
    <ReservationID>1234</ReservationID>
    <Status>CB</Status>
    <ConfNum/>
    <CancelPolicy />
    <CancelNum/>
    <PrimaryPassenger>
        <FirstName>Chris</FirstName>
        <LastName>Miller</LastName>
        <Phone>5551234567</Phone>
        <Phone2>5551234568</Phone2>
        <CellPhone>5551234555</CellPhone>
        <EmailAddress>cmiller@example.com</EmailAddress>
    </PrimaryPassenger>
    <ServiceType>110</ServiceType>
    <ClassOfService />
    <PickupLocation>
        <LocationType>100</LocationType>
        <Airport>
            <AirportCode />
            <Flight>
                <CarrierCode />
                <FlightNumber />
                <ArrivalDateTime />
            </Flight>
        </Airport>
        <TrainStation>
            <StationCode />
            <StationName />
            <City />
            <State />
            <Train>
                <CarrierCode />
                <CarrierName />
                <TrainNumber />
            </Train>
        </TrainStation>
        <Address>209 Madison St #400</Address>
        <City>Alexandria</City>
        <State>VA</State>
        <Country>US</Country>
        <PostalCode>22314</PostalCode>
        <ExtraNotes />
    </PickupLocation>
    <DropoffLocation>
        <LocationType>200</LocationType>
        <Airport>
            <AirportCode>DCA</AirportCode>
            <Flight>
                <CarrierCode>UA</CarrierCode>
                <FlightNumber>333</FlightNumber>
                <DepartureDateTime>2012-02-19T11:29:00</DepartureDateTime>
            </Flight>
        </Airport>
        <TrainStation>
            <StationCode />
            <StationName />
            <City />
            <State />
            <Train>
                <CarrierCode />
                <CarrierName />
                <TrainNumber />
                <DepartureDateTime />
            </Train>
        </TrainStation>
        <Address />
        <City />
        <State />
        <Country />
        <PostalCode />
        <ExtraNotes />
    </DropoffLocation>
    <StartDateTime>2012-02-19T09:00:00</StartDateTime>
    <EndDateTime />
    <PickupInstructions>pick me up</PickupInstructions>
    <DropoffInstructions>None</DropoffInstructions>
    <LanguageCode>en-us</LanguageCode>
    <Currency>USD</Currency>
    <NumPassengers>1</NumPassengers>
    <RequestedDriver />
    <SpecialServiceRequest />
    <PickupServiceArrangement />
    <DropoffServiceArrangement />
    <ExtraStopArrangement />
    <RateInfo>
        <RateID>5</RateID>
        <Rate>42.50</Rate>
        <RateTypeCode>E</RateTypeCode>
        <CategoryCode />
        <MinHours />
        <Currency>US</Currency>
        <NoRateText />
        <DiscountType />
        <BasePrice>35.00</BasePrice>
        <ServiceCharge>5.00</ServiceCharge>
        <SurCharge desc="fuel">1.00</SurCharge>
        <Tax>1.50</Tax>
        <ExtraPickupCharge />
        <ExtraDropoffCharge />
        <OptionalExtraStopCharge />
        <OptionalExtraTimeCharge />
        <Message />
    </RateInfo>
    <RateDisclaimer />
    <Vehicle>
        <VehicleType>100</VehicleType>
        <Description>This is a Sedan.</Description>
        <MaxPassengers>1</MaxPassengers>
        <VehicleID>12</VehicleID>
    </Vehicle>
    <Vendor>
        <VendorCode>LML</VendorCode>
        <VendorName>LimoVendor</VendorName>
        <PhoneNumber>4354654654</PhoneNumber>
    </Vendor>
    <ProviderFeedback />
    <FormOfPayment>
        <Cash />
        <Check />
        <DirectBilling />
        <CreditCard>
            <Type>VI</Type>
            <Number>XXXXXXXXXXXX1111</Number>
            <Expiration>2013-02-19</Expiration>
        </CreditCard>
    </FormOfPayment>
    <AccountingInfo>
        <AccountingField1>715</AccountingField1>
        <AccountingField2>temp@outtask.com</AccountingField2>
        <AccountingField3>11</AccountingField3>
        <AccountingField4>Development</AccountingField4>
        <AccountingField5/>
    </AccountingInfo>
</CC_LimoPostBackRequest>

Response

SAP Concur responds to the supplier request with a result message.

Content Types

application/xml

Response Body

The response will include a CC_LimoPostBackResponse parent element, with the following child elements:

Successful post:

Element Name Description
Success This element contains the message detailing the change.

Failed post:

Element Name Description
Version The API version, currently 1.0.
Error This element contains the error text.

XML Example of Successful Response

HTTPS/1.1 200 OK
Content-Type: application/xml

<CC_LimoPostBackResponse>
    <Success>Updated Trip Status successfully.</Success>
</CC_LimoPostBackResponse>

XML Example of Response with Rrror

<CC_LimoPostBackResponse>
    <Version>1.0</Version>
    <Error>This reservation does not exist in the SAP Concur database.</Error>
</CC_LimoPostBackResponse>

HOTEL-SERVICE-2

Direct Connect - Hotel v2 - Appendix

./media/image1.png

Request

<?xml version="1.0" encoding="UTF-8"?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
  <Header xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <authentication xmlns="http://www.concur.com/webservice/auth">
      <userid>testLogin123</userid>
      <password>txxxxxxxxxxxx;</password>
    </authentication>
  </Header>
  <Body xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <OTA_HotelSearchRQ xmlns="http://www.opentravel.org/OTA/2003/05"
                       EchoToken="5ADE581A-8A7C-4DA5-A67B-EED4E58A80E2"
                       Version="4" PrimaryLangID="en" AltLangID="en" MaxResponses="100">
      <POS>
        <Source ISOCurrency="USD">
          <RequestorID Type="1" ID="HTL011235"></RequestorID>
        </Source>
      </POS>
      <Criteria>
        <Criterion>
          <Position Latitude="47.61037" Longitude="-122.20067"></Position>
          <Radius Distance="5" DistanceMax="30" UnitOfMeasureCode="1"></Radius>
          <StayDateRange Start="2018-02-12" End="2018-02-13"></StayDateRange>
        </Criterion>
      </Criteria>
    </OTA_HotelSearchRQ>
  </Body>
</Envelope>

Response

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
  <soap:Body>
    <OTA_HotelSearchRS xmlns="http://www.opentravel.org/OTA/2003/05" xmlns:ns2="http://www.concur.com/webservice/auth" AltLangID="en" EchoToken="FC6F5CDE-2D55-49A4-AE22-056AF980ADF4" PrimaryLangID="en" Version="4">
      <Success/>
      <Properties>
        <Property ChainCode="HI" ChainName="Holiday Inn" HotelCode="22222" HotelName="Holiday Inn Express Sunshine">
          <Position Latitude="47.61038" Longitude="-122.20068"/>
          <Address>
            <AddressLine>99 East 27th Street</AddressLine>
            <CityName>Bellevue</CityName>
            <PostalCode>98009</PostalCode>
            <StateProv StateCode="WA">Washington</StateProv>
            <CountryName Code="US">United States of America</CountryName>
          </Address>
          <ContactNumbers>
            <ContactNumber PhoneNumber="+14255551234" PhoneTechType="1"/>
          </ContactNumbers>
          <Award Rating="4"/>
          <HotelAmenity Code="173"/>
          <HotelAmenity Code="255"/>
          <TPA_Extensions>
            <HotelPreference>not_preferred</HotelPreference>
            <TPA_HotelPreviewImageURI>
              <URL>https://production.example.com/hotel-image.jpg</URL>
            </TPA_HotelPreviewImageURI>
            <TPA_PropertyReferenceInfo>
              <PropertyReference ReferenceCatalogCode="1376249" ReferenceCatalogName="giata"/>
            </TPA_PropertyReferenceInfo>
          </TPA_Extensions>
        </Property>
        <Property>
          ... additional Property nodes here for all returned hotels
        </Property>
      </Properties>
    </OTA_HotelSearchRS>
  </soap:Body>
</soap:Envelope>

Availability

The initial Search request (see above) is followed up by an multi-property Availability request. In the example request below Concur requests the availability for 13 properties. This could because the initial search only yielded 13 properties or the configuration per vendor is set to request availability for a maximum of 13 properties.

Request

<?xml version="1.0" encoding="UTF-8"?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
  <Header xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <authentication xmlns="http://www.concur.com/webservice/auth">
      <userid>testLogin123</userid>
      <password>txxxxxxxxxxxx;</password>
    </authentication>
  </Header>
  <Body xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <OTA_HotelAvailRQ xmlns="http://www.opentravel.org/OTA/2003/05"
                      EchoToken="5ADE581A-8A7C-4DA5-A67B-EED4E58A80E2"
                      Version="5" PrimaryLangID="en" AltLangID="en">
      <POS>
        <Source ISOCurrency="USD">
          <RequestorID Type="1" ID="HTL011235"></RequestorID>
        </Source>
      </POS>
      <AvailRequestSegments>
        <AvailRequestSegment>
          <HotelSearchCriteria>
            <Criterion>
              <HotelRef ChainCode="HI" HotelCode="22222"></HotelRef>
            </Criterion>
            <Criterion>
              <HotelRef ChainCode="AB" HotelCode="50709"></HotelRef>
            </Criterion>
            <Criterion>
              <HotelRef ChainCode="CY" HotelCode="765336"></HotelRef>
            </Criterion>
            <Criterion>
              <HotelRef ChainCode="HH" HotelCode="468159"></HotelRef>
            </Criterion>
            <Criterion>
              <HotelRef ChainCode="EM" HotelCode="70346"></HotelRef>
            </Criterion>
            <Criterion>
              <HotelRef ChainCode="AB" HotelCode="52198"></HotelRef>
            </Criterion>
            <Criterion>
              <HotelRef ChainCode="HI" HotelCode="697768"></HotelRef>
            </Criterion>
            <Criterion>
              <HotelRef ChainCode="HH" HotelCode="14411"></HotelRef>
            </Criterion>
            <Criterion>
              <HotelRef ChainCode="YX" HotelCode="436533"></HotelRef>
            </Criterion>
            <Criterion>
              <HotelRef ChainCode="PW" HotelCode="459980"></HotelRef>
            </Criterion>
            <Criterion>
              <HotelRef ChainCode="HI" HotelCode="419430"></HotelRef>
            </Criterion>
            <Criterion>
              <HotelRef ChainCode="WY" HotelCode="92103"></HotelRef>
            </Criterion>
            <Criterion>
              <HotelRef ChainCode="WG" HotelCode="252272"></HotelRef>
            </Criterion>
          </HotelSearchCriteria>
          <StayDateRange Start="2018-02-12" End="2018-02-13"></StayDateRange>
          <RoomStayCandidates>
            <RoomStayCandidate>
              <GuestCounts>
                <GuestCount AgeQualifyingCode="10" Count="1"></GuestCount>
              </GuestCounts>
            </RoomStayCandidate>
          </RoomStayCandidates>
        </AvailRequestSegment>
      </AvailRequestSegments>
    </OTA_HotelAvailRQ>
  </Body>
</Envelope>

Response

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
  <soap:Body>
    <OTA_HotelAvailRS xmlns="http://www.opentravel.org/OTA/2003/05" xmlns:ns2="http://www.concur.com/webservice/auth" AltLangID="en" EchoToken="FC6F5CDE-2D55-49A4-AE22-056AF980ADF4" PrimaryLangID="en" Version="5">
      <Success/>
      <RoomStays>
        <RoomStay>
          <RoomTypes>
            <RoomType RoomID="b3da298f">
              <RoomDescription>
                <Text>Deluxe Room with sweeping view of the city. 2 queen beds and sofa bed.</Text>
              </RoomDescription>
            </RoomType>
          </RoomTypes>
          <RatePlans>
            <RatePlan AvailabilityStatus="AvailableForSale" RatePlanID="TOGG3BU">
              <Guarantee GuaranteeType="GuaranteeRequired" />
              <CancelPenalties>
                <CancelPenalty NoCancelInd="true">
                  <Deadline AbsoluteDeadline="2018-02-12T18:00:00"/>
                </CancelPenalty>
              </CancelPenalties>
              <MealsIncluded Breakfast="false" />
            </RatePlan>
          </RatePlans>
          <RoomRates>
            <RoomRate RatePlanID="TOGG3BU" RoomID="b3da298f">
              <Rates>
                <Rate RateTimeUnit="FullDuration">
                  <PaymentPolicies>
                    <GuaranteePayment>
                      <AcceptedPayments>
                        <AcceptedPayment>
                          <PaymentCard>
                            <CardType>VISA</CardType>
                          </PaymentCard>
                        </AcceptedPayment>
                      </AcceptedPayments>
                    </GuaranteePayment>
                    <GuaranteePayment>
                      <AcceptedPayments>
                        <AcceptedPayment>
                          <PaymentCard>
                            <CardType>Mastercard</CardType>
                          </PaymentCard>
                        </AcceptedPayment>
                      </AcceptedPayments>
                    </GuaranteePayment>
                  </PaymentPolicies>
                  <Total AmountAfterTax="161.10" AmountBeforeTax="152.70" CurrencyCode="USD"/>
                  <RateDescription>
                    <Text>Promotional rate</Text>
                    <Text>Free valet/self parking and turndown service</Text>
                  </RateDescription>
                </Rate>
              </Rates>
            </RoomRate>
          </RoomRates>
          <GuestCounts>
            <GuestCount Count="1"/>
          </GuestCounts>
          <TimeSpan Start="2018-02-12" End="2018-02-13" />
          <BasicPropertyInfo HotelCode="22222" />
        </RoomStay>
        <RoomStay>
          <RoomTypes>
            <RoomType RoomID="f7631619">
              <RoomDescription>
                <Text>Standard Room with garden view. 1 king bed and sofa bed.</Text>
              </RoomDescription>
            </RoomType>
          </RoomTypes>
          <RatePlans>
            <RatePlan AvailabilityStatus="AvailableForSale" RatePlanID="MB4YV34">
              <Guarantee GuaranteeType="Deposit"/>
              <CancelPenalties>
                <CancelPenalty NoCancelInd="true">
                  <Deadline AbsoluteDeadline="2018-02-12T18:00:00"/>
                </CancelPenalty>
              </CancelPenalties>
              <MealsIncluded Breakfast="false" />
            </RatePlan>
          </RatePlans>
          <RoomRates>
            <RoomRate RatePlanID="MB4YV34" RoomID="f7631619">
              <Rates>
                <Rate RateTimeUnit="FullDuration">
                  <PaymentPolicies>
                    <GuaranteePayment>
                      <AcceptedPayments>
                        <AcceptedPayment>
                          <PaymentCard>
                            <CardType>VISA</CardType>
                          </PaymentCard>
                        </AcceptedPayment>
                      </AcceptedPayments>
                    </GuaranteePayment>
                    <GuaranteePayment>
                      <AcceptedPayments>
                        <AcceptedPayment>
                          <PaymentCard>
                            <CardType>Mastercard</CardType>
                          </PaymentCard>
                        </AcceptedPayment>
                      </AcceptedPayments>
                    </GuaranteePayment>
                  </PaymentPolicies>
                  <Total AmountAfterTax="149.00" AmountBeforeTax="141.23" CurrencyCode="USD"/>
                  <RateDescription>
                    <Text>Hot Deal</Text>
                    <Text>Free valet/self parking</Text>
                  </RateDescription>
                </Rate>
              </Rates>
            </RoomRate>
          </RoomRates>
          <GuestCounts>
            <GuestCount Count="1"/>
          </GuestCounts>
          <TimeSpan End="2018-02-13" Start="2018-05-12" />
          <BasicPropertyInfo HotelCode="50709" />
        </RoomStay>
        <RoomStay>
          ... additional RoomStay nodes follow here for all available rooms for all hotels (properties) per
          Availability request
        </RoomStay>
      </RoomStays>
    </OTA_HotelAvailRS>
  </soap:Body>
</soap:Envelope>

Search results displayed

Search results page displaying hotels, based on Search response, and their rates, based on Availability response:

./media/image1.png

WIth Availability response also cancellation information comes which can be displayed in separate popup:

./media/image1.png

Hotel Description

./media/image1.png

Request

<?xml version="1.0" encoding="UTF-8"?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
  <Header xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <authentication xmlns="http://www.concur.com/webservice/auth">
      <userid>testLogin123</userid>
      <password>txxxxxxxxxxxx;</password>
    </authentication>
  </Header>
  <Body xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <OTA_HotelDescriptiveInfoRQ xmlns="http://www.opentravel.org/OTA/2003/05"
                                EchoToken="A78F3641-8674-43F9-B58C-AD928D1A75D9"
                                Version="3" PrimaryLangID="en" AltLangID="en">
      <POS>
        <Source ISOCurrency="USD">
          <RequestorID Type="1" ID="HTL011235"></RequestorID>
        </Source>
      </POS>
      <HotelDescriptiveInfos>
        <HotelDescriptiveInfo ChainCode="CY" HotelCode="419430"></HotelDescriptiveInfo>
      </HotelDescriptiveInfos>
    </OTA_HotelDescriptiveInfoRQ>
  </Body>
</Envelope>

Response

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
  <soap:Body>
    <OTA_HotelDescriptiveInfoRS xmlns="http://www.opentravel.org/OTA/2003/05"
                                xmlns:ns2="http://www.concur.com/webservice/auth">
      <Success/>
      <HotelDescriptiveContents>
        <HotelDescriptiveContent ChainCode="CY" HotelCode="419430" HotelName="Courtyard Prague Airport">
          <HotelInfo>
            <Descriptions>
              <DescriptiveText>Prague (PRG): The Europort building which housed the hotel is located in front of the
                arrivial and departure halls at Prague-ruzyne Airport. The hotel will have direct access to the
                airport’s infrastructure and offer connections to both the walkway and transporation routes. The
                conveniently located Courtyard Prague Airport provides its guests upscale accommodation outside the
                buzzing city centre. Kept in a cosy elegant design, the comfortable rooms are fitted with coffee and tea
                maker and nice sitting and working area. The magnificent atrium with its modern structure and nice
                garden invites to stay and relax. Directly situated at Prague’s international airport, the hotel is
                about 16 kilometres from the city centre and the historic castle. In the nearby surroundings, guests can
                enjoy horseback riding, biking or kayaking. Oléo Pazzo Mediterranean Bistro is a contemporary restaurant
                decorated in warm and coulourful style with a show kitchen and a trendy bar. Other features are a
                fitness,a business center,meeting rooms.
              </DescriptiveText>
            </Descriptions>
          </HotelInfo>
          <MultimediaDescriptions>
            <MultimediaDescription>
              <ImageItems>
                <ImageItem>
                  <ImageFormat>
                    <URL>https://iut-foto-origin.hrsstatic.com/foto/3/8/9/8/389886/389886_fi_451616.jpg</URL>
                  </ImageFormat>
                </ImageItem>
                <ImageItem>
                  <ImageFormat>
                    <URL>https://iut-foto-origin.hrsstatic.com/foto/3/8/9/8/389886/389886_u_6302064.jpg</URL>
                  </ImageFormat>
                </ImageItem>
                <ImageItem>
                  <ImageFormat>
                    <URL>https://iut-foto-origin.hrsstatic.com/foto/3/8/9/8/389886/389886_u_451896.jpg</URL>
                  </ImageFormat>
                </ImageItem>
              </ImageItems>
            </MultimediaDescription>
          </MultimediaDescriptions>
          <TPA_Extensions>
            <Description Name="First Description">
              <Text>First line of first description.</Text>
              <Text>Second line of first description.</Text>
            </Description>
            <Description>
              <Text>Second description without name.</Text>
            </Description>
          </TPA_Extensions>
        </HotelDescriptiveContent>
      </HotelDescriptiveContents>
    </OTA_HotelDescriptiveInfoRS>
  </soap:Body>
</soap:Envelope>

Hotel Details displayed

./media/image1.png

Reservation

./media/image1.png ./media/image1.png

./media/image1.png ./media/image1.png

Request

<?xml version="1.0" encoding="UTF-8"?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
  <Header xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <authentication xmlns="http://www.concur.com/webservice/auth">
      <userid>testLogin123</userid>
      <password>txxxxxxxxxxxx;</password>
    </authentication>
  </Header>
  <Body xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <OTA_HotelResRQ xmlns="http://www.opentravel.org/OTA/2003/05"
                    EchoToken="6C85DDBD-EB62-444D-B2C3-F59BDF65BE98"
                    Version="6" PrimaryLangID="en" AltLangID="en">
      <POS>
        <Source ISOCurrency="USD">
          <RequestorID Type="1" ID="HTL011235"></RequestorID>
        </Source>
      </POS>
      <HotelReservations>
        <HotelReservation>
          <RoomStays>
            <RoomStay>
              <RatePlans>
                <RatePlan RatePlanID="XNFYP4I">
                  <Guarantee GuaranteeType="CC/DC/Voucher">
                    <GuaranteesAccepted>
                      <GuaranteeAccepted>
                        <PaymentCard CardCode="VI" ExpireDate="1220">
                          <CardType Code="VI">VISA</CardType>
                          <CardHolderName>HOTELSERVICEAMADEUS TESTUSERMOCK</CardHolderName>
                        </PaymentCard>
                      </GuaranteeAccepted>
                    </GuaranteesAccepted>
                  </Guarantee>
                </RatePlan>
              </RatePlans>
              <TimeSpan Start="2018-02-12" End="2018-02-13"></TimeSpan>
              <BasicPropertyInfo HotelCode="419430"></BasicPropertyInfo>
            </RoomStay>
          </RoomStays>
          <ResGuests>
            <ResGuest>
              <Profiles>
                <ProfileInfo>
                  <Profile>
                    <Customer Gender="Unknown">
                      <PersonName Language="en">
                        <GivenName>HOTELSERVICEAMADEUS</GivenName>
                        <Surname>TESTUSERMOCK</Surname>
                      </PersonName>
                      <Telephone PhoneNumber="3141011001"></Telephone>
                      <Email>hrs_hs2_amadeus_mock@concurautm3.com</Email>
                      <Address>
                        <AddressLine>123 Sesame St.</AddressLine>
                        <CityName>Alexandria</CityName>
                        <PostalCode>22314</PostalCode>
                        <StateProv></StateProv>
                        <CountryName Code="US">USA</CountryName>
                      </Address>
                      <CitizenCountryName Code="US"></CitizenCountryName>
                    </Customer>
                    <CompanyInfo>
                      <CompanyName>CONCURTECH</CompanyName>
                    </CompanyInfo>
                  </Profile>
                </ProfileInfo>
              </Profiles>
              <GuestCounts>
                <GuestCount Count="1"></GuestCount>
              </GuestCounts>
            </ResGuest>
          </ResGuests>
        </HotelReservation>
      </HotelReservations>
    </OTA_HotelResRQ>
  </Body>
</Envelope>

Response

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
  <soap:Body>
    <OTA_HotelResRS xmlns="http://www.opentravel.org/OTA/2003/05"
                    xmlns:ns2="http://www.concur.com/webservice/auth"
                    ResResponseType="Reserved">
      <Success/>
      <HotelReservations>
        <HotelReservation>
          <UniqueID ID="88618333"/>
          <RoomStays>
            <RoomStay>
              <RatePlans>
                <RatePlan RatePlanID="EZ57LL7">
                  <CancelPenalties CancelPolicyIndicator="true">
                    <CancelPenalty>
                      <PenaltyDescription>
                        <Text>test cancel policy 1</Text>
                      </PenaltyDescription>
                    </CancelPenalty>
                    <CancelPenalty>
                      <Deadline AbsoluteDeadline="2018-02-22T18:00"/>
                    </CancelPenalty>
                  </CancelPenalties>
                </RatePlan>
              </RatePlans>
              <RoomRates>
                <RoomRate>
                  <Rates>
                    <Rate RoomPricingType="Per stay">
                      <PaymentPolicies>
                        <GuaranteePayment>
                          <AcceptedPayments>
                            <AcceptedPayment>
                              <PaymentCard CardCode="VI"/>
                            </AcceptedPayment>
                          </AcceptedPayments>
                        </GuaranteePayment>
                        <GuaranteePayment>
                          <AcceptedPayments>
                            <AcceptedPayment>
                              <PaymentCard CardCode="MC"/>
                            </AcceptedPayment>
                          </AcceptedPayments>
                        </GuaranteePayment>
                        <GuaranteePayment>
                          <AcceptedPayments>
                            <AcceptedPayment>
                              <PaymentCard CardCode="CA"/>
                            </AcceptedPayment>
                          </AcceptedPayments>
                        </GuaranteePayment>
                        <GuaranteePayment>
                          <AcceptedPayments>
                            <AcceptedPayment>
                              <PaymentCard CardCode="IK"/>
                            </AcceptedPayment>
                          </AcceptedPayments>
                        </GuaranteePayment>
                        <GuaranteePayment>
                          <AcceptedPayments>
                            <AcceptedPayment>
                              <PaymentCard CardCode="AX"/>
                            </AcceptedPayment>
                          </AcceptedPayments>
                        </GuaranteePayment>
                      </PaymentPolicies>
                      <Total AmountAfterTax="85.00" AmountBeforeTax="85.00" CurrencyCode="EUR"/>
                    </Rate>
                  </Rates>
                </RoomRate>
              </RoomRates>
              <TimeSpan End="2018-02-23" Start="2018-02-22"/>
              <BasicPropertyInfo HotelCode="50709" HotelName="Alexander Plaza">
                <Address>
                  <AddressLine>Rosenstr. 1</AddressLine>
                  <CityName>Berlin</CityName>
                  <CountryName Code="DEU">Federal Republic of Germany</CountryName>
                  <StateProv StateCode="BE">Berlin disctrict</StateProv>
                  <PostalCode>BE123</PostalCode>
                </Address>
                <ContactNumbers>
                  <ContactNumber PhoneNumber="3024001722"/>
                </ContactNumbers>
              </BasicPropertyInfo>
            </RoomStay>
          </RoomStays>
          <ResGuests>
            <ResGuest>
              <Profiles>
                <ProfileInfo>
                  <Profile>
                    <Customer>
                      <PersonName>
                        <GivenName>TESTER</GivenName>
                        <Surname>Testovic</Surname>
                      </PersonName>
                    </Customer>
                  </Profile>
                </ProfileInfo>
              </Profiles>
            </ResGuest>
          </ResGuests>
          <ResGlobalInfo>
            <Comments>
              <Comment Name="Comment 1">
                <Text>First line of Comment 1.</Text>
                <Text>Second line of Comment 1.</Text>
              </Comment>
              <Comment>
                <Text>First line of Comment 2 without name.</Text>
              </Comment>
            </Comments>
          </ResGlobalInfo>
        </HotelReservation>
      </HotelReservations>
    </OTA_HotelResRS>
  </soap:Body>
</soap:Envelope>

Read

./media/image1.png ./media/image1.png ./media/image1.png

Request

<?xml version="1.0" encoding="UTF-8"?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
  <Header xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <authentication xmlns="http://www.concur.com/webservice/auth">
      <userid>testLogin123</userid>
      <password>txxxxxxxxxxxx;</password>
    </authentication>
  </Header>
  <Body xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <OTA_ReadRQ xmlns="http://www.opentravel.org/OTA/2003/05"
                EchoToken="4E1B8BF4-ACBD-4709-9FCC-B59EB2550086"
                Version="5.002" PrimaryLangID="en" AltLangID="en">
      <POS>
        <Source ISOCurrency="USD">
          <RequestorID Type="1" ID="HTL011235"></RequestorID>
        </Source>
      </POS>
      <UniqueID Type="14" ID="88618333"></UniqueID>
    </OTA_ReadRQ>
  </Body>
</Envelope>

Response

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
  <soap:Body>
    <OTA_HotelResRS xmlns="http://www.opentravel.org/OTA/2003/05"
                    xmlns:ns2="http://www.concur.com/webservice/auth"
                    ResResponseType="Reserved">
      <Success/>
      <HotelReservations>
        <HotelReservation>
          <UniqueID ID="88621190"/>
          <RoomStays>
            <RoomStay>
              <RatePlans>
                <RatePlan RatePlanID="P4PGI5Q">
                  <CancelPenalties CancelPolicyIndicator="true">
                    <CancelPenalty>
                      <PenaltyDescription>
                        <Text>test cancel policy 1</Text>
                      </PenaltyDescription>
                    </CancelPenalty>
                    <CancelPenalty>
                      <PenaltyDescription>
                        <Text>test cancel policy 2</Text>
                      </PenaltyDescription>
                      <PenaltyDescription>
                        <Text>test cancel policy 3</Text>
                      </PenaltyDescription>
                    </CancelPenalty>
                    <CancelPenalty>
                      <Deadline AbsoluteDeadline="2018-02-22T18:00"/>
                    </CancelPenalty>
                  </CancelPenalties>
                </RatePlan>
              </RatePlans>
              <RoomRates>
                <RoomRate>
                  <Rates>
                    <Rate RoomPricingType="Per stay">
                      <PaymentPolicies>
                        <GuaranteePayment>
                          <AcceptedPayments>
                            <AcceptedPayment>
                              <PaymentCard CardCode="VI"/>
                            </AcceptedPayment>
                          </AcceptedPayments>
                        </GuaranteePayment>
                        <GuaranteePayment>
                          <AcceptedPayments>
                            <AcceptedPayment>
                              <PaymentCard CardCode="MC"/>
                            </AcceptedPayment>
                          </AcceptedPayments>
                        </GuaranteePayment>
                        <GuaranteePayment>
                          <AcceptedPayments>
                            <AcceptedPayment>
                              <PaymentCard CardCode="CA"/>
                            </AcceptedPayment>
                          </AcceptedPayments>
                        </GuaranteePayment>
                        <GuaranteePayment>
                          <AcceptedPayments>
                            <AcceptedPayment>
                              <PaymentCard CardCode="IK"/>
                            </AcceptedPayment>
                          </AcceptedPayments>
                        </GuaranteePayment>
                        <GuaranteePayment>
                          <AcceptedPayments>
                            <AcceptedPayment>
                              <PaymentCard CardCode="AX"/>
                            </AcceptedPayment>
                          </AcceptedPayments>
                        </GuaranteePayment>
                      </PaymentPolicies>
                      <Total AmountAfterTax="208.95" AmountBeforeTax="208.95" CurrencyCode="EUR"/>
                    </Rate>
                  </Rates>
                </RoomRate>
              </RoomRates>
              <TimeSpan End="2018-02-23" Start="2018-02-22"/>
              <BasicPropertyInfo ChainCode="1609" HotelCode="10517" HotelName="Radisson Blu Hotel">
                <Address>
                  <AddressLine>Karl-Liebknecht-Str. 3</AddressLine>
                  <CityName>Berlin</CityName>
                  <CountryName Code="DEU">Federal Republic of Germany</CountryName>
                  <StateProv StateCode="BE">Berlin disctrict</StateProv>
                  <PostalCode>BE123</PostalCode>
                </Address>
                <ContactNumbers>
                  <ContactNumber PhoneNumber="30238280"/>
                </ContactNumbers>
              </BasicPropertyInfo>
            </RoomStay>
          </RoomStays>
          <ResGuests>
            <ResGuest>
              <Profiles>
                <ProfileInfo>
                  <Profile>
                    <Customer>
                      <PersonName>
                        <GivenName>TESTER</GivenName>
                        <Surname>Testovic</Surname>
                      </PersonName>
                    </Customer>
                  </Profile>
                </ProfileInfo>
              </Profiles>
            </ResGuest>
          </ResGuests>
          <ResGlobalInfo>
            <Comments>
              <Comment Name="Comment 1">
                <Text>First line of Comment 1.</Text>
                <Text>Second line of Comment 1.</Text>
              </Comment>
              <Comment>
                <Text>First line of Comment 2 without name.</Text>
              </Comment>
            </Comments>
          </ResGlobalInfo>
        </HotelReservation>
      </HotelReservations>
    </OTA_HotelResRS>
  </soap:Body>
</soap:Envelope>

Itinerary displayed

./media/image1.png ./media/image1.png

Cancel

./media/image1.png ./media/image1.png

Request

<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
  <Header xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <authentication xmlns="http://www.concur.com/webservice/auth">
      <userid>testLogin123</userid>
      <password>txxxxxxxxxxxx;</password>
    </authentication>
  </Header>
  <Body xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <OTA_CancelRQ xmlns="http://www.opentravel.org/OTA/2003/05" CancelType="Cancel"
                  EchoToken="2186EB84-23D9-4977-B8A5-B5083C8DE228"
                  Version="3" PrimaryLangID="en" AltLangID="en">
      <POS>
        <Source ISOCurrency="USD">
          <RequestorID Type="1" ID="HTL011235"></RequestorID>
        </Source>
      </POS>
      <UniqueID Type="14" ID="88618333"></UniqueID>
    </OTA_CancelRQ>
  </Body>
</Envelope>

Response

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
  <soap:Body>
    <OTA_CancelRS xmlns="http://www.opentravel.org/OTA/2003/05"
                  xmlns:ns2="http://www.concur.com/webservice/auth"
                  Status="Cancelled">
      <Success/>
      <UniqueID ID="88618333" Type="14"/>
      <UniqueID ID="27607" Type="15"/>
    </OTA_CancelRS>
  </soap:Body>
</soap:Envelope>

./media/image1.png ./media/image1.png

Direct Connect - Hotel v2 - Availability

Message to retrieved the availability of hotels.

SOAPAction OTA Name Message Structure
availability HotelAvail OTA_HotelAvailRQ

Request

<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
  <Header xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <authentication xmlns="http://www.concur.com/webservice/auth">
      <userid>user</userid>
      <password>password</password>
    </authentication>
  </Header>
  <Body xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <OTA_HotelAvailRQ xmlns="http://www.opentravel.org/OTA/2003/05" EchoToken="test_request_id" Version="5"
                      PrimaryLangID="de" AltLangID="de">
      <POS>
        <Source ISOCurrency="USD">
          <RequestorID Type="1" ID="HTL011235"></RequestorID>
        </Source>
      </POS>
      <AvailRequestSegments>
        <AvailRequestSegment>
          <HotelSearchCriteria>
            <Criterion>
              <HotelRef ChainCode="ZZ" HotelCode="111222"></HotelRef>
            </Criterion>
          </HotelSearchCriteria>
          <StayDateRange Start="2018-10-26" End="2018-10-28"></StayDateRange>
          <RoomStayCandidates>
            <RoomStayCandidate>
              <GuestCounts>
                <GuestCount AgeQualifyingCode="10" Count="1"></GuestCount>
              </GuestCounts>
            </RoomStayCandidate>
          </RoomStayCandidates>
          <TPA_Extensions>
            <SearchSessionToken>5EA6C45E55104704E4</SearchSessionToken>
          </TPA_Extensions>
        </AvailRequestSegment>
      </AvailRequestSegments>
    </OTA_HotelAvailRQ>
  </Body>
</Envelope>

Schema

OTA_HotelAvailRQ

Name Type Description
AvailRequestSegments complex Required A collection of AvailRequestSegment. Each segment includes a collection of criteria that requests a bookable entity, which may include designated rate plans, room types, amenities or services. The request can be used for guest rooms or other inventory items for which availability is sought. Each segment will be presumed to have a unique date range for each request. SAP Concur will only ever send one AvailRequestSegments.

AvailRequestSegments

Name Type Description
AvailRequestSegment complex Required To accommodate the ability to perform multiple requests within one message, the availability request contains the repeating element, AvailRequestSegment. Each segment includes a collection of criteria that requests a bookable entity, which may include designated rate plans, room types, amenities or services. The request can be used for guest rooms or other inventory items for which availability is sought. Each segment will be presumed to have a unique date range for each request. SAP Concur will only ever send one AvailRequestSegment.

AvailRequestSegment

Name Type Description
HotelSearchCriteria complex Required Specified hotel search criteria. SAP Concur will send only one (1) HotelSearchCriteria.
StayDateRange complex Range of dates using ISO 8601.
TPA_Extensions/SearchSessionToken stringLength1to128 The token obtained from Search response that links the Search results to Availability and Reservation requests.

HotelSearchCriteria

Name Type Description
Criterion complex Required Refer to Criterion in Search. Note that for Availability the Criterion will only have the HotelRef element. Other elements will not be sent. HotelSearchCriteria can contain multiple Criterion elements. Each will have a unique HotelCode per Availability request.

Criterion

Name Type Description
HotelRef/HotelCode stringLength1to16 Required The code that uniquely identifies a single hotel property. The hotel code is decided by vendors.
HotelRef/ChainCode stringLength1to8 The code that identifies a hotel chain or management group. The hotel chain code is decided between vendors. This attribute is optional if the hotel is an independent property that can be identified by the HotelCode attribute.

StayDateRange

Name Type Description
Start date, or time, or datetime Required The starting value of the time span.
End date, or time, or datetime Required The ending value of the time span.

RoomStayCandidates

Name Type Description
RoomStayCandidate complex Required Element used to identify available room products.

RoomStayCandidate

Name Type Description
GuestCounts complex Required A collection of guest counts associated with room stay.

GuestCounts

Name Type Description
GuestCount complex Required A recurring element that identifies the number of guests and ages of the guests. It currently contains hardcoded values only. See GuestCount below.

GuestCount

Name Type Description
Count integer Required SAP Concur only supports one guest. Supported values: 1
AgeQualifyingCode integer Required Supported values: 10

Response

The maximum allowed size of OTA_HotelAvailRS is 5 MB. Any response that exceeds this limit shall be dropped.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
  <soap:Body>
    <OTA_HotelAvailRS xmlns="http://www.opentravel.org/OTA/2003/05" Version="5">
      <Success/>
      <RoomStays>
        <RoomStay>
          <RoomTypes>
            <RoomType RoomID="1">
              <RoomDescription>
                <Text>Test room description.</Text>
              </RoomDescription>
            </RoomType>
          </RoomTypes>
          <RatePlans>
            <RatePlan RatePlanID="XNFYP4I" AvailabilityStatus="ChangeDuringStay">
              <Guarantee GuaranteeType="GuaranteeRequired" />
              <CancelPenalties>
                <CancelPenalty NoCancelInd="true">
                  <Deadline AbsoluteDeadline="2017-01-26T18:00:00"/>
                  <PenaltyDescription>
                    <Text>REFUNDABLE</Text>
                    <Text>Cancellation without penalty allowed before 2017-01-26T18:00:00</Text>
                  </PenaltyDescription>
                </CancelPenalty>
              </CancelPenalties>
              <MealsIncluded Breakfast="true"/>
              <RatePlanDescription>
                <Text>Test rate plan description.</Text>
              </RatePlanDescription>
            </RatePlan>
          </RatePlans>
          <RoomRates>
            <RoomRate RoomID="1" RatePlanID="XNFYP4I">
              <Rates>
                <Rate RateTimeUnit="FullDuration">
                  <PaymentPolicies>
                    <GuaranteePayment>
                      <AcceptedPayments>
                        <AcceptedPayment>
                          <PaymentCard CardCode="VI"/>
                        </AcceptedPayment>
                      </AcceptedPayments>
                    </GuaranteePayment>
                  </PaymentPolicies>
                  <Total AmountAfterTax="348.00" AmountBeforeTax="248.00" CurrencyCode="EUR"/>
                  <RateDescription>
                    <Text>Test rate description. Both before and after tax.</Text>
                  </RateDescription>
                  <TPA_Extensions>
                    <RequireSeriesCode>true</RequireSeriesCode>
                  </TPA_Extensions>
                </Rate>
              </Rates>
            </RoomRate>
          </RoomRates>
          <TimeSpan End="2018-10-28" Start="2018-10-26"/>
          <BasicPropertyInfo HotelCode="419430"/>
        </RoomStay>
      </RoomStays>
      <TPA_Extensions RateDetailsInd="false"></TPA_Extensions>
    </OTA_HotelAvailRS>
  </soap:Body>
</soap:Envelope>

Schema

OTA_HotelAvailRS

Name Type Description
RoomStays complex Required A collection of details on the room stay including time span of this room stay, and financial information related to the room stay, including guarantee, deposit, payment, and cancellation penalties.
TPA_Extensions/RateDetailsInd boolean If true or omitted, ratedetails will not be called to retrieve the cancellation policy and rate change details; if false, ratedetails will be called.

RoomStays

Name Type Description
RoomStay complex Details on the room stay including time span of this room stay, and financial information related to the room stay, including guarantee, deposit, payment, and cancellation penalties. A room stay represents one (1) hotel. It can be excluded to identify there is no rate available at the hotel.

RoomStay

For a description of the relationship between the RoomID and RatePlanID refer to "Relationship between RoomID and RatePlanID".

Name Type Description
RoomTypes complex Required Details on the room type.
RatePlans complex Required A collection of rate plans associated with a particular room stay. The rate plan element is used to contain all the rate information for a single rate plan Code (example: RACK) for a given date range. A given rate plan may have variable rates, over the effective period of the rate plan, this is represented by the child element rates.
RoomRates complex Required List of room rates.
TimeSpan datetimespan Required The time span which covers the room stay. The attributes of the OTA DateTimeSpan data type are based on the W3C base data types of timeInstant and timeDuration using ISO 8601.
BasicPropertyInfo complex Property Information for the room stay.

RoomTypes

Name Type Description
RoomType complex Required Provides details regarding rooms, usually guest rooms. The room description text will be used for each room (defined as a RoomRate) which specifies the same RoomID.

RoomType

Name Type Description
RoomID stringLength1to16 Required A string value representing the unique identification of a room if the request is looking for a specific room type.
RoomDescription complex Textual information regarding the room.

RoomDescription

Name Type Description
Text string Required If multiple text elements are provided, the contents will be concatenated. All text passed is HTML encoded.

RatePlans

Name Type Description
RatePlan complex Required Defines the details of the rate plan as used in the booking process. Policies and descriptions that apply to a rate plan. Information significant to defining a rate plan.

RatePlan

Name Type Description
RatePlanID stringLength1to64 Required A text field used to indicate a special ID code that is associated with the rate and is essential in the reservation request in order to obtain the rate. Examples: Corporate ID.
AvailabilityStatus stringLength1to32 Required Used to specify an availability status for the rate plan. Supported values: AvailableForSale, ChangeDuringStay.
Guarantee complex Required Guarantee information that applies to the rate plan. SAP Concur only expects one (1) Guarantee element per RatePlan.
CancelPenalties complex Required if RateDetailsInd is true or not present Collection of cancellation penalties. If the cancel penalties are not provided SAP Concur will display: "Cancellation policy not provided by vendor".
MealsIncluded complex Defines which meals are included with this rate program.
RatePlanDescription complex Textual information regarding the Rate Plan.

RatePlanDescription

Name Type Description
Text string Required If multiple text elements are specified, the contents of this element will be rendered as a paragraph. All text passed is HTML encoded.

Guarantee

Name Type Description
GuaranteeType string Required The guarantee information to hold a reservation.

Supported GuaranteeTypes

GuaranteeType Description
Deposit In SAP Concur this value is seen as RequiredDeposit.
DepositRequired In SAP Concur this value is seen as RequiredDeposit.
CC/DC/Voucher In SAP Concur this value is seen as RequiredGuarantee.
PrePay In SAP Concur this value is seen as RequiredPrepay.
None In SAP Concur this value is seen as Never. No guarantee is required if user books a room with this type.
GuaranteeRequired RequiredGuarantee. If the Guarantee type cannot be mapped to any accepted type, it will be set to RequiredGuarantee. This value is the default.

Supported GuaranteeRequired

GuaranteeRequired Description
always Guarantee is required all the time independently on deposit account setting.
never Guarantee is never required.
default Guarantee is required if no deposit account is set up.

CancelPenalties

Name Type Description
CancelPenalty complex Required Defines the cancellation penalty of the hotel facility.

CancelPenalty

Name Type Description
NoCancelInd boolean If true, the reservation cannot be cancelled once the cancellation deadline has expired. False or missing flag will be treated as rate being not cancellable.
PenaltyDescription complex Text description of the penalty in a given language. This element may contain a maximum of 9 children text fields. Any excess text elements are dropped.
Deadline complex Cancellation deadline.

PenaltyDescription

Name Type Description
Text string Required Formatted text content in a given language. All text passed is HTML encoded.

Deadline

Name Type Description
AbsoluteDeadline time or datetime Required Defines the absolute deadline in ISO8601 format and in UTC timezone.

MealsIncluded

Name Type Description
Breakfast boolean If true, indicates breakfast is included. If false, indicates it is excluded. In both cases this information is shown to a customer in the rate description. The MealsIncluded element must be omitted to avoid any adjustment to the rate description.

RoomRates

Name Type Description
RoomRate complex Required Contains the rate details.

RoomRate

Name Type Description
RoomID stringLength1to16 Required Room Type ID. The combination of RoomID and RatePlanID must be unique for a RoomStay.
RatePlanID stringLength1to64 Required Rate plan ID for which this rate is applicable for.
Rates complex Required Contains the rate for the given room. SAP Concur only expects one (1) rate inside the Rates element. Refer to Rate Details for rate change details.

Rates

Name Type Description
Rate complex Required Contains the rate for the given room. Only one (1) Rate element is expected. Refer to Rate Details for rate change details.

Rate

Name Type Description
RateTimeUnit string Indicates the time unit for the rate. Supported values: FullDuration, Day. Default: FullDuration
PaymentPolicies complex Payment policies for this rate.
Total complex Required A description of the rate.
RateDescription complex A textual description of a rate. Only one (1) Rate Description element is expected.
TPA_extensions complex TPA extensions for a rate.

PaymentPolicies

Name Type Description
GuaranteePayment complex Element containing the guarantee payment type.

GuaranteePayment

Name Type Description
AcceptedPayments complex Required If used, at least one (1) AcceptedPayment should be present.

AcceptedPayments

Name Type Description
AcceptedPayment complex Required Accepted payment type.

AcceptedPayment

Name Type Description
PaymentCard complex Required Description of payment type.

PaymentCard

Name Type Description
CardType complex Required String representation of a card type. Allowed values: AmericanExpress, BankOfAmerica, BritishAirways, CapitalOne, Chase, Citibank, ContinentalAirlines, DeltaAirlines, DiscoverCard, Disney, Eurocard, Hilton, Hyatt, Mariott, Mastercard, RitzCarlton, SouthwestAirlines, StarwoodHotels, UnitedAirlines, USAirways, VISA, Other_. See Code and Description if card type is other_.

CardType

Name Type Description
Code string If CardType is Other_, use this attribute for card code. Examples: AX, VI.
Description string If CardType is Other_, use this attribute for card description.

Total

Name Type Description
AmountBeforeTax string The total amount not including any associated tax. Examples: sales tax, VAT, GST
AmountAfterTax string Required The total amount including all associated taxes. Examples: sales tax, VAT, GST
CurrencyCode alphaLength3 Required Currency code.

RateDescription

Name Type Description
Text string Required If multiple text elements are provided, the contents will be concatenated. All text passed is HTML encoded.

TPA_Extensions

Name Type Description
RequireSeriesCode boolean If true, the CVV code is required for the given rate. When false or not provided, the rate will be treated as CVV code not required.

Timespan

Name Type Description
Start date, time, or datetime Required The starting value of the time span.
End date, time, or datetime Required The ending value of the time span.

BasicPropertyInfo

Name Type Description
HotelCode complex Required Refer to the Property element described in Search.

Relationship between RoomID and RatePlanID

The combination of these IDs must be unique per RoomStay. IDs with the same values can be redefined in multiple RoomStays.

<OTA_HotelAvailRS>
  <Success/>
  <!-- Hotel #1 with 3 rates -->
  <RoomStays>
    <RoomStay>
      <RoomTypes>
        <RoomType RoomID="RT1">...</RoomType>
        <RoomType RoomID="RT2">...</RoomType>
      </RoomTypes>
      <RatePlans> <!-- Contains cancellation policy info, guarantee type etc. -->
        <RatePlan AvailabilityStatus="AvailableForSale" RatePlanID="RP1">...</RatePlan>
        <RatePlan AvailabilityStatus="AvailableForSale" RatePlanID="RP2">...</RatePlan>
        <RatePlan AvailabilityStatus="AvailableForSale" RatePlanID="RP3">...</RatePlan>
      </RatePlans>
      <RoomRates> <!-- Represents unique rate (hotel room), contains description part 1, rate cost & supported credit card etc. -->
        <RoomRate RatePlanID="RP1" RoomID="RT1">...</RoomRate>
        <RoomRate RatePlanID="RP2" RoomID="RT2">...</RoomRate> <!-- Note: RT2 is reused in two Room Rates -->
        <RoomRate RatePlanID="RP3" RoomID="RT2">...</RoomRate>
      </RoomRates>
      ...
    </RoomStay>
  </RoomStays>
<!-- Hotel #2 with 2 rates -->
  <RoomStays>
    <RoomStay>
      <RoomTypes>
        <RoomType RoomID="RT1">...</RoomType>
        <RoomType RoomID="RT2">...</RoomType>
      </RoomTypes>
      <RatePlans>
        <RatePlan AvailabilityStatus="AvailableForSale" RatePlanID="RP1">...</RatePlan>
        <RatePlan AvailabilityStatus="AvailableForSale" RatePlanID="RP2">...</RatePlan>
      </RatePlans>
      <RoomRates>
        <RoomRate RatePlanID="RP1" RoomID="RT1">...</RoomRate>
        <RoomRate RatePlanID="RP2" RoomID="RT2">...</RoomRate>
      </RoomRates>
      ...
    </RoomStay>
  </RoomStays>
  ...
</OTA_HotelAvailRS>

Direct Connect - Hotel v2 - Cancel

Cancel

Message used to indicate to the hotel supplier that a given reservation should be cancelled.

SOAPAction OTA Name Message Structure
cancel Cancel OTA_CancelRQ

Request

<?xml version="1.0" encoding="UTF-8"?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
  <Header xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <authentication xmlns="http://www.concur.com/webservice/auth">
      <userid>user</userid>
      <password>password</password>
    </authentication>
  </Header>
  <Body xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <OTA_CancelRQ xmlns="http://www.opentravel.org/OTA/2003/05" EchoToken="test_request_id" Version="3"
                  PrimaryLangID="en" AltLangID="en" CancelType="Cancel">
      <POS>
        <Source ISOCurrency="USD">
          <RequestorID Type="1" ID="HTL011235"></RequestorID>
        </Source>
      </POS>
      <UniqueID Type="14" ID="11112222"></UniqueID>
    </OTA_CancelRQ>
  </Body>
</Envelope>

OTA_CancelRQ

Name Type Description
UniqueID complex Required Element to hold the type and the ID of the reservation to be cancelled.

UniqueID

Name Type Description
Type string Required UniqueID with Type of 14 identifies the reservation to cancel.
ID stringLength1to32 Required A unique identifying value assigned by the creating system.

Response

The maximum allowed size of OTA_CancelRS is 150 KB. Any response that exceeds this limit shall be dropped.

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
  <soap:Body>
    <OTA_CancelRS xmlns="http://www.opentravel.org/OTA/2003/05" Version="3" Status="Cancelled">
      <Success/>
      <UniqueID ID="11112222" Type="14"/>
      <UniqueID ID="12122" Type="15"/>
    </OTA_CancelRS>
  </soap:Body>
</soap:Envelope>

OTA_CancelRS

Name Type Description
Status string Required Supported values: Cancelled, Unsuccessful
Success successType An element that is not intended to contain any data. The mere presence of a success element within the response message indicates that the incoming request message was processed successfully.
UniqueID string Required See UniqueID above. SAP Concur expects two (2) UniqueIDs to be returned in the response. The first with an Type of 14 containing the original reservation number, and the second Type of 15 containing a confirmation number. Both elements are mandatory.

Direct Connect - Hotel v2 - Descriptive Information

Descriptive Info

Message to retrieve descriptive details about a given hotel. This may include text and/or a number of URL pointed to hosted images. Concur does not host any hotel images.

SOAPAction OTA Name Message Structure
detail HotelDescriptiveInfo OTA_HotelDescriptiveInfoRQ

Request

<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
  <Header xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <authentication xmlns="http://www.concur.com/webservice/auth">
      <userid>user</userid>
      <password>password</password>
    </authentication>
  </Header>
  <Body xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <OTA_HotelDescriptiveInfoRQ xmlns="http://www.opentravel.org/OTA/2003/05" EchoToken="test_request_id" Version="3" PrimaryLangID="de" AltLangID="de">
      <POS>
        <Source ISOCurrency="USD">
          <RequestorID Type="1" ID="HTL011235"></RequestorID>
        </Source>
      </POS>
      <HotelDescriptiveInfos>
        <HotelDescriptiveInfo ChainCode="AB" HotelCode="2575"></HotelDescriptiveInfo>
      </HotelDescriptiveInfos>
    </OTA_HotelDescriptiveInfoRQ>
  </Body>
</Envelope>

OTA_HotelDescriptiveInfoRQ

Name Type Description
HotelDescriptiveInfos complex Required Collection of items for data from multiple hotels. SAP Concur will only ever send one (1) HotelDescriptiveInfo.

HotelDescriptiveInfos

Name Type Description
HotelDescriptiveInfo complex Required This allows the requestor to indicate which specific information is requested if complete hotel details are not required.

HotelDescriptiveInfo

Name Type Description
ChainCode stringLength1to8 The code that identifies a hotel chain or management group. The hotel chain code is decided between vendors. This attribute is optional if the hotel is an independent property that can be identified by the HotelCode attribute.
HotelCode stringLength1to16 Required The code that uniquely identifies a single hotel property. The hotel code is decided between vendors.

Response

The maximum allowed size of OTA_HotelDescriptiveInfoRS is 150 KB. Any response that exceeds this limit will be dropped.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
  <soap:Body>
    <OTA_HotelDescriptiveInfoRS xmlns="http://www.opentravel.org/OTA/2003/05" Version="3">
      <Success/>
      <HotelDescriptiveContents>
        <HotelDescriptiveContent ChainCode="ZZ" HotelCode="2575" HotelName="Torbräu">
          <HotelInfo>
            <Descriptions>
              <DescriptiveText>Hotel description</DescriptiveText>
            </Descriptions>
          </HotelInfo>
          <MultimediaDescriptions>
            <MultimediaDescription>
              <ImageItems>
                <ImageItem>
                  <ImageFormat>
                    <URL>https://production.example.com/hotel-image.jpg</URL>
                  </ImageFormat>
                </ImageItem>
              </ImageItems>
            </MultimediaDescription>
          </MultimediaDescriptions>
          <TPA_Extensions>
            <Description Name="This will be a header">
              <Text>First line of first description.</Text>
              <Text>Second line of first description.</Text>
            </Description>
            <Description>
              <Text>Second description without name.</Text>
            </Description>
          </TPA_Extensions>
        </HotelDescriptiveContent>
      </HotelDescriptiveContents>
    </OTA_HotelDescriptiveInfoRS>
  </soap:Body>
</soap:Envelope>

OTA_HotelDescriptiveInfoRS

Name Type Description
HotelDescriptiveContents complex Required Contains hotel details content which is made up of text and image URLs.

HotelDescriptiveContents

Name Type Description
HotelDescriptiveContent complex Required Contains hotel details content which is made up of text and image URLs. SAP Concur expects one (1) HotelDescriptiveContent.

HotelDescriptiveContent

Name Type Description
HotelCode stringLength1to16 Required The code that uniquely identifies a single hotel property. The hotel code is decided between vendors.
HotelName stringLength1to128 Required A text field used to communicate the proper name of the hotel. SAP Concur always expects the Hotel Name to be provided.
HotelInfo complex Contains descriptive information about a hotel.
TPA_Extensions complex SAP Concur specific extensions.
MultimediaDescriptions complex Multimedia information about a collection of multimedia objects. SAP Concur expects one (1) MultimediaDescription element.

HotelInfo

Name Type Description
Descriptions complex Contains descriptive information about a hotel. SAP Concur expects one (1) Descriptions.

Descriptions

Name Type Description
DescriptiveText string Descriptive text that describes the hotel. SAP Concur expects one (1) DescriptiveText

TPA_Extensions

Name Type Description
Description complex Represents text which will be rendered in the UI in the form of a heading and a paragraph.

Description

Name Type Description
name stringLength1to64 The contents of this element will be rendered as a heading on the hotel details page.
Text string Required The contents of this element will be rendered as a paragraph. SAP Concur expects a maximum of 20 text elements per description, which will be concatenated to into one (1) paragraph.

MultimediaDescriptions

Name Type Description
MultimediaDescription complex Holds a list of ImageItems, each representing a single hotel image.

MultimediaDescription

Name Type Description
ImageItems complex Holds a list of ImageItem, each representing a single hotel image. SAP Concur expects up to a maximum of 200 ImageItem elements.

ImageItems

Name Type Description
ImageItem complex One (1) ImageItem per hotel image.

ImageItem

Name Type Description
ImageFormat complex Format of image.

ImageFormat

Name Type Description
URL string Required Contains a HTTPS URL pointing to a hotel image. The URLs are used in a client-side gallery widget, which works best with .png and .jpg files.

Direct Connect - Hotel v2 - Error Handling

SAP Concur is able to handle HTTP errors, but the preference is for the supplier to return an OTA error whenever possible. SAP Concur only ever expects one OTA error per message. Any extra errors will be ignored. Currently OTA Warnings are not supported and will be ignored.

If the error is specifically related to application level errors, please do not respond with any other error types (HTTP etc.). If you have server level issues, then it is OK to respond with HTTP standard error codes.

Errors should always be returned in a response. For example:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
  <soap:Body>
    <OTA_HotelSearchRS xmlns="http://www.opentravel.org/OTA/2003/05"
                       AltLangID="en"
                       EchoToken="11111111-2222-3333-4444-555555555555" PrimaryLangID="en"
                       Version="4">
      <Errors>
        <Error Code="322" ShortText="No availability" Type="13"></Error>
      </Errors>
    </OTA_HotelSearchRS>
  </soap:Body>
</soap:Envelope>

If an error is present in any message, then the content of that message is discarded and only the error element is processed. Any text from the supplier will be logged and a SAP Concur message will be displayed to the user.

Currently SAP Concur does not support displaying of supplier generated errors directly in the UI.

SAP Concur only uses the very first error that is returned, therefore any excess error elements are dropped. Any errors without a Type attribute will automatically be treated as 1 meaning Unknown. See the Error Types table below.

Name Type Description
Errors complex Element used to hold error elements. SAP Concur only expects one (1) error element. An empty errors element will be treated as an Unknown error.

Errors

Name Type Description
Error complex Element to describe a particular error. Extra text can be placed inside this element, however SAP Concur expects the error message to be sent in the ShortText attribute.

Error

Name Type Description
Type string An error type code. See the Error Types below.
ShortText string Required A description of the error. The content of this attribute will be logged, but never displayed to the user.
Code string Required An error code for a specific error.

Error Types

SAP Concur supports the following Error Type Codes in any of the responses:

Code Name Description
1 Unknown Indicates an unknown error.
2 No implementation Indicates that the target business system has no implementation for the intended request.
13 Application error Indicates that an involved back-end application returned an error which is passed back in the response message.

Note: The OTA Error-Type code of 4 - Authentication (indicates the message lacks adequate security credentials) is not expected by SAP Concur. For all authentication errors SAP Concur expects an HTTP 403.

SAP Concur expects the following errors under the given error types:

Error Type Code 1: Unknown
Error Code Description Example
188 Transaction error For errors not specified in other codes. Internal supplier log ID can be provided in ShortText for debugging.
Error Type Code 2: No Implementation
Error Code Description Example
1 Not implemented The supplier can respond with this error if the end point called is not yet implemented.
Error Type Code 13: Application Error
Error Code Description Example
242 Credit card number is invalid or missing Missing credit card number.
320 Invalid value Comma separated node or attribute and sent value should be provided in the content of the error element. Example: <Error Code="320" ShortText="Invalid value" Type="13">StayDateRange:2019-11-33</Error>
322 No availability Hotel Codes should be provided in content of the element. Example: <Error Code="322" ShortText="No availability" Type="13">HTL4444,HTL5555</Error>
424 No hotels found which match this input Search parameters - geo-code and radius should be provided in content of the element and formatted as tokenized list: Latitude, Longitude, Radius, Unit of Measure code. Example: <Error Code="322" ShortText="No availability" Type="13">50.111,40.222,5,2</Error>
95 Booking already cancelled Booking already cancelled.
438 Requested rate not available List of comma separated RatePlanID's should be provided in content of the element. Example: <Error Code="322" ShortText="No availability" Type="13">111,222</Error>
748 Invalid corporate ID Requestor ID should be provided in the content of the element.
400 Invalid property code List of comma separated hotel codes should be provided in content of the element. Example: <Error Code="322" ShortText="No availability" Type="13">HTL4444,HTL5555</Error>
385 Invalid confirmation or cancellation number Reservation ID should be provided in content of the element.

Direct Connect - Hotel v2 - Headers

SAP Concur will send the user-name and password in both the HTTP header and the SOAP header. If the username and password generates an authentication error, then SAP Concur expects an HTTP 403 response.

HTTP Headers

SAP Concur will send the following HTTP headers in every request. The contents of the Authentication header will be repeated in the SOAP payload. Please note that some libraries used to handle the requests may be case sensitive.

Name Type Description
Authorization string A Base64 encoded string in the form of Basic <username:password>.
SOAPAction string The message type. The action will always be sent in lowercase. Example: search
Content-Type string All communication with the HS2 API is by way of a application/xml content type.
Accept string SAP Concur will always set the Accept header to application/xml.
Accept-Charset string SAP Concur will always set the Accept-Charset header to utf-8.
concur-correlationid string This unique code can be used during troubleshooting as it identifies the API call in the log files.
concur-traveleruuid string UUID that identifies the traveler within concur, will always be sent once profile creation is completed.
concur-loginid string Login ID of traveler within concur. Only sent when available.

Supported Soapactions:

Soapaction Functionality
search Used to perform Search
availability Used to perform Availability
ratedetails Used to perform Rate Details
detail Used to perform Hotel Description
book Used to perform Reservation
read Used to perform Read Itinerary
cancel Used to perform Cancel

Troubleshooting

In order to assist with troubleshooting, SAP Concur provides a unique correlationId in the request header. The key to look for is correlationid. This unique code can be used during troubleshooting as it identifies the API call in the log files. You should record this information in your own API call logs as well so that you can pass this information on to the SAP Concur support team.

Example HTTP Header from network capture:

Accept: application/xml
Accept-Charset: utf-8
Authorization: *******************
concur-correlationid: A75CE5BC-90BA-4BF8-8DEA-69FA2E66E936
concur-loginid: abc@concur.com
concur-traveleruuid: <valid uuid>
Content-Type: application/xml; charset="utf-8"
SOAPAction: search
Accept-Encoding: gzip

Soap Header

The Soap header nested in the Envelope will contain an authentication element.

authentication

Name Type Description
userid string Required Contains the authentication details.
password string Required Contains the authentication details.

Sample:

<Header xmlns="http://schemas.xmlsoap.org/soap/envelope/">
  <authentication xmlns="http://www.concur.com/webservice/auth">
    <userid>testLogin123</userid>
    <password>xxxxxxxxxxxx</password>
  </authentication>
</Header>

Login and password are provided by the Hotel supplier for SAP Concur as API consumer, not per customer.

OTA Message Headers

Every message must contain the following required attributes and elements. On top of these each message may specify extra attributes and elements. Refer to a specific messages' page for details.

Request Message Headers

Name Type Description
EchoToken stringLength1to128 Required A reference for additional message identification, assigned by the requesting host system.
Version double Required The OpenTravel message version indicated by a decimal value.
PrimaryLangID string Required The primary language preference for the message encoded as ISO 639-1.
AltLangID string Required The alternate language for a customer or message encoded as ISO 639-1.
POS complex Required Point of Sale (POS) identifies the party or connection channel making the request.

POS

Name Type Description
Sources complex Required This holds the details about the requestor. Max Occurrence: 10

Source

SAP Concur will always send the ISO Currency.

Name Type Description
ISOCurrency alphaLength3 Required Currency code.
RequestorID complex An identifier of the entity making the request Examples: ATA/IATA/ID number, Electronic Reservation Service Provider (ERSP), Association of British Travel Agents (ABTA)

RequestorID

Name Type Description
Type stringLength1to32 Required Supported value: 1
ID stringLength1to32 Required The requestor ID.

Response Message Headers

The supplier is required to respond with the following attributes and elements in the root of any message. Each message may specify extra attributes and elements. Refer to a specific messages' page for details.

Name Type Description
EchoToken stringLength1to128 Required A reference for additional message identification, assigned by the requesting host system. When a request message includes an echo token the corresponding response message MUST include an echo token with an identical value.
Timestamp datetime Required Timestamp of the response operation.
Version double Required The OpenTravel message version indicated by a decimal value.
PrimaryLangID string Required The primary language preference for the message encoded as ISO 639-1.
AltLangID string Required The alternate language for a customer or message encoded as ISO 639-1.
Success / Error complex Required Indicates Success Or Error. Refer to the Error Handling page for more details.

Direct Connect - Hotel v2 - Introduction

Overview

The Hotel Services v2 Direct Connect provides a method for Travel users to access hotel inventory.

The Hotel Service 2.0 API from SAP Concur is a specification based on OTA 2015 standard for Hotel Suppliers. Please refer to XSD schema of the service and WSDL service description. This Guide provides information how the Hotel Supplier can make their content available for Concur Travel users using Hotel Service 2.0 API. Once the Hotel Supplier has developed and certified their interface with SAP Concur, their inventory will begin appearing in hotel searches by opted-in Travel users. This API has client/server architecture, where SAP Concur acts as client, pulling information from the Hotel Supplier, who acts as server, responding to SAP Concur’s requests. This guide specifies the request and response format required by SAP Concur.

This call-out differs from the in-bound SAP Concur web services in the following ways:

Contents

Product Restrictions

SAP Concur products are highly configurable, and not all clients will have access to all features.

Supported Operations

Non-Functional Requirements

Payload Limits

Operation Maximum response content-length
Search 1 MB
Availability 5 MB
Descriptive Information 150 KB
Rate Details 5 MB
Reservation 150 KB
Read Itinerary 150 KB
Cancel 150 KB

Responses that exceed these limits will be dropped and handled as error responses.

Operation Ideal response time
Search <4 seconds
Availability <10 seconds
Descriptive Information <1 second
Rate Details <2 seconds
Reservation <10 seconds
Read Itinerary <1 second
Cancel <10 seconds

Achieving lower response times helps get information to the traveler sooner which leads to a better user experience. SAP Concur understands that not every hotel program manages their own inventory and requires relays out to other vendors and the numbers above take that scenario into consideration.

All endpoints carry a timeout of 55 seconds. No endpoints will attempt a retry in the event there is a timeout.

SAP Concur has monitoring in place for each endpoint and will open a ticket with suppliers if a significant degradation or variance of service quality is detected.

NOTE: To prevent no show fees, duplicate bookings and other similar issues, SAP Concur recommends the Hotel Supplier auto-cancel the reservation if a corresponding ReadRQ message is not sent by SAP Concur within 5 minutes after the HotelResRS message was sent to SAP Concur.

Maximum Connections and Throttling

SAP Concur is unable to share details regarding maximum connections and/or throttling questions due to their sensitivity in nature.

Emergency Technical Contact

The Hotel supplier needs to provide emergency technical contact email that will be used for communication in case of blocking technical issues.

Testing Environment

To allow SAP Concur performing testing, the Hotel Supplier needs to provide testing URL or specify properties for testing in production URL. SAP Concur needs to be able to perform test bookings with testing credit cards.

Security

PCI DSS Compliance

As sensitive data and payment card details are transferred via API, the Hotel Suppliers need to comply with PCI DSS standard. SAP Concur is compliant with PCI DSS standard and undergoes regular security audits.

HTTPS

SAP Concur requires TLS 1.2 (Transport Layer Security) SSL protocol for file transfers. The Hotel Supplier will provide SAP Concur HTTPS URL of its end-point. Standard HTTPS port 443 should be used.

URLs

SAP Concur will receive a single URL from the Hotel Supplier. All requests will go to that URL.

For details of all required HTTP headers refer to Headers

SAP Concur is using date as xs:date XML type "2017-05-01".

Handling of HTML

CDATA and HTML code inside of XML nodes and attributes are not allowed. These data will be escaped. The hotel suppliers should not use XML special characters - predefined entities: &, <, >, ", ' inside of ID elements like RatePlanID.

Message Structure

All messages to and from the HS2 API follow this structure:

Requests

Note: The Header element in a request must contain the Authentication element.

Responses

Note: The header in the response does not need the Authentication element.

Direct Connect - Hotel v2 - Rate Details

Message to retrieve the details of a hotel rate.

SOAPAction OTA Name Message Structure
ratedetails HotelAvail OTA_HotelAvailRQ

Request

<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
  <Header xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <authentication xmlns="http://www.concur.com/webservice/auth">
      <userid>user</userid>
      <password>password</password>
    </authentication>
  </Header>
  <Body xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <OTA_HotelAvailRQ xmlns="http://www.opentravel.org/OTA/2003/05" EchoToken="test_request_id" Version="5"
                      PrimaryLangID="de" AltLangID="de" RateDetailsInd="true">
      <POS>
        <Source ISOCurrency="USD">
          <RequestorID Type="1" ID="HTL011235"></RequestorID>
        </Source>
      </POS>
      <AvailRequestSegments>
        <AvailRequestSegment>
          <HotelSearchCriteria>
            <Criterion>
              <RatePlanCandidates>
                <RatePlanCandidate RatePlanID="XNFYP4I">
                  <HotelRefs>
                    <HotelRef ChainCode="ZZ" HotelCode="111222"></HotelRef>
                  </HotelRefs>
                </RatePlanCandidate>
              </RatePlanCandidates>
            </Criterion>
          </HotelSearchCriteria>
          <StayDateRange Start="2018-10-26" End="2018-10-28"></StayDateRange>
          <RoomStayCandidates>
            <RoomStayCandidate>
              <GuestCounts>
                <GuestCount AgeQualifyingCode="10" Count="1"></GuestCount>
              </GuestCounts>
            </RoomStayCandidate>
          </RoomStayCandidates>
          <TPA_Extensions>
            <SearchSessionToken>5EA6C45E55104704E4</SearchSessionToken>
          </TPA_Extensions>
        </AvailRequestSegment>
      </AvailRequestSegments>
    </OTA_HotelAvailRQ>
  </Body>
</Envelope>

Schema

OTA_HotelAvailRQ

Name Type Description
RateDetailsInd boolean Required Always set to true for ratedetails.
AvailRequestSegments complex Required A collection of AvailRequestSegment. Each segment includes a collection of criteria that requests a bookable entity, which may include designated rate plans, room types, amenities or services. The request can be used for guest rooms or other inventory items for which availability is sought. Each segment will be presumed to have a unique date range for each request. SAP Concur will only ever send one AvailRequestSegments.

AvailRequestSegments

Name Type Description
AvailRequestSegment complex Required To accommodate the ability to perform multiple requests within one message, the availability request contains the repeating element, AvailRequestSegment. Each segment includes a collection of criteria that requests a bookable entity, which may include designated rate plans, room types, amenities or services. The request can be used for guest rooms or other inventory items for which availability is sought. Each segment will be presumed to have a unique date range for each request. SAP Concur will only ever send one AvailRequestSegment.

AvailRequestSegment

Name Type Description
HotelSearchCriteria complex Required Specified hotel search criteria. SAP Concur will send only one (1) HotelSearchCriteria.
StayDateRange complex Range of dates using ISO 8601.
TPA_Extensions/SearchSessionToken stringLength1to128 The token obtained from Search response that links the Search results to Availability and Reservation requests.

HotelSearchCriteria

Name Type Description
Criterion complex Required Refer to Criterion in Search. Note that for Rate Details the Criterion will only have one RatePlanCandidate element.

Criterion

Name Type Description
RatePlanCandidates/RatePlanCandidate complex Required Specified rate plan candidate.

RatePlanCandidate

Name Type Description
RatePlanID StringLength1to64 Required The code that uniquely identifies the rate plan.
HotelRefs/HotelRef/HotelCode stringLength1to16 The code that uniquely identifies a single hotel property. The hotel code is decided by vendors.
HotelRefs/HotelRef/ChainCode stringLength1to8 The code that identifies a hotel chain or management group. The hotel chain code is decided between vendors. This attribute is optional if the hotel is an independent property that can be identified by the HotelCode attribute.

StayDateRange

Name Type Description
Start date, or time, or datetime Required The starting value of the time span.
End date, or time, or datetime Required The ending value of the time span.

RoomStayCandidates

Name Type Description
RoomStayCandidate complex Required Element used to identify available room products.

RoomStayCandidate

Name Type Description
GuestCounts complex Required A collection of guest counts associated with room stay.

GuestCounts

Name Type Description
GuestCount complex Required A recurring element that identifies the number of guests and ages of the guests. It currently contains hardcoded values only. See GuestCount below.

GuestCount

Name Type Description
Count integer Required SAP Concur only supports one guest. Supported values: 1
AgeQualifyingCode integer Required Supported values: 10

Response

The maximum allowed size of OTA_HotelAvailRS is 5 MB. Any response that exceeds this limit shall be dropped.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
  <soap:Body>
    <OTA_HotelAvailRS xmlns="http://www.opentravel.org/OTA/2003/05" Version="5">
      <Success/>
      <RoomStays>
        <RoomStay>
          <RoomTypes>
            <RoomType RoomID="1">
              <RoomDescription>
                <Text>Test room description.</Text>
              </RoomDescription>
            </RoomType>
          </RoomTypes>
          <RatePlans>
            <RatePlan RatePlanID="XNFYP4I" AvailabilityStatus="ChangeDuringStay">
              <Guarantee GuaranteeType="GuaranteeRequired" />
              <CancelPenalties>
                <CancelPenalty NoCancelInd="true">
                  <Deadline AbsoluteDeadline="2017-01-26T18:00:00"/>
                  <PenaltyDescription>
                    <Text>Cancellation without penalty allowed before 2017-01-26T18:00:00</Text>
                  </PenaltyDescription>
                </CancelPenalty>
              </CancelPenalties>
              <MealsIncluded Breakfast="true"/>
              <RatePlanDescription>
                <Text>Test rate plan description.</Text>
              </RatePlanDescription>
            </RatePlan>
          </RatePlans>
          <RoomRates>
            <RoomRate RoomID="1" RatePlanID="XNFYP4I">
              <RoomRateDescription>
                <Text>Basic Wifi Included.</Text>
              </RoomRateDescription>
              <Rates>
                <Rate RateTimeUnit="FullDuration" EffectiveDate="2018-10-26" ExpireDate="2018-10-27">
                  <PaymentPolicies>
                    <GuaranteePayment>
                      <AcceptedPayments>
                        <AcceptedPayment>
                          <PaymentCard CardCode="VI"/>
                        </AcceptedPayment>
                      </AcceptedPayments>
                    </GuaranteePayment>
                  </PaymentPolicies>
                  <Total AmountAfterTax="199.00" AmountBeforeTax="149.00" CurrencyCode="EUR"/>
                  <RateDescription>
                    <Text>Test rate description. Both before and after tax.</Text>
                  </RateDescription>
                </Rate>
                <Rate RateTimeUnit="FullDuration" EffectiveDate="2018-10-27" ExpireDate="2018-10-28">
                  <Total AmountAfterTax="149.00" AmountBeforeTax="99.00" CurrencyCode="EUR"/>
                </Rate>
              </Rates>
            </RoomRate>
          </RoomRates>
          <TimeSpan End="2018-10-28" Start="2018-10-26"/>
          <BasicPropertyInfo ChainCode="ZZ" HotelCode="419430"/>
        </RoomStay>
      </RoomStays>
      <TPA_Extensions RateDetailsInd="true"></TPA_Extensions>
    </OTA_HotelAvailRS>
  </soap:Body>
</soap:Envelope>

Schema

OTA_HotelAvailRS

Name Type Description
RoomStays complex Required A collection of details on the room stay including time span of this room stay, and financial information related to the room stay, including guarantee, deposit, payment, and cancellation penalties.
TPA_Extensions/RateDetailsInd boolean Always set to true for ratedetails.

RoomStays

Name Type Description
RoomStay complex Required Details on the room stay including time span of this room stay, and financial information related to the room stay, including guarantee, deposit, payment, and cancellation penalties. A room stay represents one (1) hotel.

RoomStay

For a description of the relationship between the RoomID and RatePlanID refer to "Relationship between RoomID and RatePlanID".

Name Type Description
RoomTypes complex Required Details on the room type.
RatePlans complex Required A collection of rate plans associated with a particular room stay. The rate plan element is used to contain all the rate information for a single rate plan Code (example: RACK) for a given date range. A given rate plan may have variable rates, over the effective period of the rate plan, this is represented by the child element rates.
RoomRates complex Required List of room rates.
TimeSpan datetimespan Required The time span which covers the room stay. The attributes of the OTA DateTimeSpan data type are based on the W3C base data types of timeInstant and timeDuration using ISO 8601.
BasicPropertyInfo complex Property Information for the room stay.

RoomTypes

Name Type Description
RoomType complex Required Provides details regarding rooms, usually guest rooms. The room description text will be used for each room (defined as a RoomRate) which specifies the same RoomID.

RoomType

Name Type Description
RoomID stringLength1to16 Required A string value representing the unique identification of a room if the request is looking for a specific room type.
RoomDescription complex Textual information regarding the room.

RoomDescription

Name Type Description
Text string Required If multiple text elements are provided, the contents will be concatenated. All text passed is HTML encoded.

RatePlans

Name Type Description
RatePlan complex Required Defines the details of the rate plan as used in the booking process. Policies and descriptions that apply to a rate plan. Information significant to defining a rate plan.

RatePlan

Name Type Description
RatePlanID stringLength1to64 Required A text field used to indicate a special ID code that is associated with the rate and is essential in the reservation request in order to obtain the rate. Examples: Corporate ID.
AvailabilityStatus stringLength1to32 Required Used to specify an availability status for the rate plan. Supported values: AvailableForSale, ChangeDuringStay.
Guarantee complex Required Guarantee information that applies to the rate plan. SAP Concur only expects one (1) Guarantee element per RatePlan.
CancelPenalties complex Required if RateDetailsInd is true Collection of cancellation penalties. If the cancel penalties are not provided SAP Concur will display: "Cancellation policy not provided by vendor".
MealsIncluded complex Defines which meals are included with this rate program.
RatePlanDescription complex Textual information regarding the Rate Plan.

RatePlanDescription

Name Type Description
Text string Required If multiple text elements are specified, the contents of this element will be rendered as a paragraph. All text passed is HTML encoded.

Guarantee

Name Type Description
GuaranteeType string Required The guarantee information to hold a reservation.

Supported GuaranteeTypes

GuaranteeType Description
Deposit In SAP Concur this value is seen as RequiredDeposit.
DepositRequired In SAP Concur this value is seen as RequiredDeposit.
CC/DC/Voucher In SAP Concur this value is seen as RequiredGuarantee.
PrePay In SAP Concur this value is seen as RequiredPrepay.
None In SAP Concur this value is seen as Never. No guarantee is required if user books a room with this type.
GuaranteeRequired RequiredGuarantee. If the Guarantee type cannot be mapped to any accepted type, it will be set to RequiredGuarantee. This value is the default.

Supported GuaranteeRequired

GuaranteeRequired Description
always Guarantee is required all the time independently on deposit account setting.
never Guarantee is never required.
default Guarantee is required if no deposit account is set up.

CancelPenalties

Name Type Description
CancelPenalty complex Required Defines the cancellation penalty of the hotel facility.

CancelPenalty

Name Type Description
NoCancelInd boolean If true, the reservation cannot be cancelled once the cancellation deadline has expired. False or missing flag will be treated as rate being not cancellable.
PenaltyDescription complex Text description of the penalty in a given language. This element may contain a maximum of 9 children text fields. Any excess text elements are dropped.
Deadline complex Cancellation deadline.

PenaltyDescription

Name Type Description
Text string Required Formatted text content in a given language. All text passed is HTML encoded.

Deadline

Name Type Description
AbsoluteDeadline time or datetime Required Defines the absolute deadline in ISO8601 format and in UTC timezone.

MealsIncluded

Name Type Description
Breakfast boolean If true, indicates breakfast is included. If false, indicates it is excluded. In both cases this information is shown to a customer in the rate description. The MealsIncluded element must be omitted to avoid any adjustment to the rate description.

RoomRates

Name Type Description
RoomRate complex Required Contains the rate details.

RoomRate

Name Type Description
RoomID stringLength1to16 Required Room Type ID. The combination of RoomID and RatePlanID must be unique for a RoomStay.
RatePlanID stringLength1to64 Required Rate plan ID for which this rate is applicable for.
Rates complex Required Contains the rate for the given room. SAP Concur only expects one (1) Rate inside the Rates element if AvailabilityStatus is AvailableForSale. It is optional to include multiple Rate for ChangeDuringStay
RoomRateDescription complex The description or name of a room rate.

Rates

Name Type Description
Rate complex Required Contains the rate for the given room. Only one (1) Rate element is expected if AvailabilityStatus is AvailableForSale. It is optional to include multiple Rate for ChangeDuringStay

Rate

Name Type Description
RateTimeUnit string Indicates the time unit for the rate. Supported values: FullDuration, Day. Default: FullDuration
EffectiveDate date, or time, or datetime For ChangeDuringStay. Indicates the start date of the time span.
ExpireDate date, or time, or datetime For ChangeDuringStay. Indicates the end date of the time span.
PaymentPolicies complex Payment policies for this rate.
Total complex Required A description of the rate.
RateDescription complex A textual description of a rate. Only one (1) Rate Description element is expected.
TPA_extensions complex TPA extensions for a rate.

RoomRateDescription

Name Type Description
Text string Required Formatted text content in a given language. All text passed is HTML encoded.

PaymentPolicies

Name Type Description
GuaranteePayment complex Element containing the guarantee payment type.

GuaranteePayment

Name Type Description
AcceptedPayments complex Required If used, at least one (1) AcceptedPayment should be present.

AcceptedPayments

Name Type Description
AcceptedPayment complex Required Accepted payment type.

AcceptedPayment

Name Type Description
PaymentCard complex Required Description of payment type.

PaymentCard

Name Type Description
CardType complex Required String representation of a card type. Allowed values: AmericanExpress, BankOfAmerica, BritishAirways, CapitalOne, Chase, Citibank, ContinentalAirlines, DeltaAirlines, DiscoverCard, Disney, Eurocard, Hilton, Hyatt, Mariott, Mastercard, RitzCarlton, SouthwestAirlines, StarwoodHotels, UnitedAirlines, USAirways, VISA, Other_. See Code and Description if card type is other_.

CardType

Name Type Description
Code string If CardType is Other_, use this attribute for card code. Examples: AX, CA, DC, DS, JC, VI. Map to AMEX, Mastercard, Diners Club, Discover, JCB, Visa
Description string If CardType is Other_, use this attribute for card description.

Total

Name Type Description
AmountBeforeTax string The total amount not including any associated tax. Examples: sales tax, VAT, GST
AmountAfterTax string Required The total amount including all associated taxes. Examples: sales tax, VAT, GST
CurrencyCode alphaLength3 Required Currency code.

RateDescription

Name Type Description
Text string Required If multiple text elements are provided, the contents will be concatenated. All text passed is HTML encoded.

Timespan

Name Type Description
Start date, time, or datetime Required The starting value of the time span.
End date, time, or datetime Required The ending value of the time span.

BasicPropertyInfo

Name Type Description
HotelCode complex Required Refer to the Property element described in Search.
Address complex Refer to Search.
ContactNumbers complex Refer to Search.

Direct Connect - Hotel v2 - Read Itinerary

Read Itinerary

Returns detailed information about a hotel reservation. Used in a process of booking a hotel to write information to Itinerary. Not invoked by user, but by automatic Concur process. Hotel Supplier should reply with HotelRes RS message in the same format, as for HotelResRQ.

SOAPAction OTA Name Message structure
Read Itinerary HotelRes OTA_ReadRQ

Request

<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
  <Header xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <authentication xmlns="http://www.concur.com/webservice/auth">
      <userid>user</userid>
      <password>password</password>
    </authentication>
  </Header>
  <Body xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <OTA_ReadRQ xmlns="http://www.opentravel.org/OTA/2003/05" EchoToken="test_request_id" Version="5.002"
                PrimaryLangID="de" AltLangID="de">
      <POS>
        <Source ISOCurrency="USD">
          <RequestorID Type="1" ID="HTL011235"></RequestorID>
        </Source>
      </POS>
      <UniqueID Type="14" ID="88618333"></UniqueID>
    </OTA_ReadRQ>
  </Body>
</Envelope>

OTA_ReadRQ

Name Type Description
UniqueID complex Required A reference to identify the booking.

UniqueID

Name Type Description
Type stringLength1to32 Required Supported value: 14
ID stringLength1to32 Required UniqueID from HotelResRS is used as reservation ID.

Response

The response to the Read Itinerary message is the same as the response to the Reservation request, which can be found under Reservation. The response content for cancelled reservations still requires fields marked as Required

Direct Connect - Hotel v2 - Reservation

Reservation Message

Message to reserve a hotel.

SOAPAction OTA Name Message Structure
book HotelRes OTA_HotelResRQ

Request

<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
  <Header xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <authentication xmlns="http://www.concur.com/webservice/auth">
      <userid>user</userid>
      <password>password</password>
    </authentication>
  </Header>
  <Body xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <OTA_HotelResRQ xmlns="http://www.opentravel.org/OTA/2003/05" EchoToken="test_request_id" Version="6"
                    PrimaryLangID="de" AltLangID="de">
      <POS>
        <Source ISOCurrency="USD">
          <RequestorID Type="1" ID="HTL011235"></RequestorID>
        </Source>
      </POS>
      <HotelReservations>
        <HotelReservation>
          <RoomStays>
            <RoomStay>
              <RatePlans>
                <RatePlan RatePlanID="ZZZZ1117">
                  <Guarantee GuaranteeType="CC/DC/Voucher">
                    <GuaranteesAccepted>
                      <GuaranteeAccepted>
                        <PaymentCard CardCode="VI" ExpireDate="1027">
                          <CardType Code="VI">VISA</CardType>
                          <CardHolderName>Jane Doe</CardHolderName>
                          <Address>
                            <StreetNmbr>600 13TH ST NE</StreetNmbr>
                            <CityName>WASHINGTON</CityName>
                            <PostalCode>20002</PostalCode>
                            <StateProv StateCode="DC">District of Columbia</StateProv>
                            <CountryName Code="US">United States of America</CountryName>
                          </Address>
                          <SeriesCode>
                            <PlainText>xxx</PlainText>
                          </SeriesCode>
                        </PaymentCard>
                      </GuaranteeAccepted>
                    </GuaranteesAccepted>
                  </Guarantee>
                </RatePlan>
              </RatePlans>
              <TimeSpan Start="2017-01-26" End="2017-01-27"></TimeSpan>
              <BasicPropertyInfo HotelCode="111222"></BasicPropertyInfo>
              <Comments>
                <Comment>
                  <Text TextFormat="PlainText">ROLLAWAY</Text>
                </Comment>
                <Comment>
                  <Text TextFormat="PlainText">FOAMPILLOWS</Text>
                </Comment>
              </Comments>
            </RoomStay>
          </RoomStays>
          <ResGuests>
            <ResGuest>
              <Profiles>
                <ProfileInfo>
                  <Profile>
                    <Customer Gender="Female" BirthDate="1987-05-12">
                      <PersonName Language="de">
                        <NamePrefix>MRS</NamePrefix>
                        <GivenName>JANE</GivenName>
                        <Surname>DOE</Surname>
                      </PersonName>
                      <Telephone PhoneNumber="703-555-6100"></Telephone>
                      <Email>jane.doe@example.com</Email>
                      <Address>
                        <AddressLine>209 Madison St Suite 400</AddressLine>
                        <CityName>Alexandria</CityName>
                        <PostalCode>22314</PostalCode>
                        <StateProv StateCode="VA"></StateProv>
                        <CountryName Code="US">United States of America</CountryName>
                      </Address>
                      <CitizenCountryName Code="US"></CitizenCountryName>
                    </Customer>
                    <CompanyInfo>
                      <CompanyName>SAP Concur</CompanyName>
                    </CompanyInfo>
                  </Profile>
                </ProfileInfo>
              </Profiles>
              <GuestCounts>
                <GuestCount Count="1"></GuestCount>
              </GuestCounts>
            </ResGuest>
          </ResGuests>
          <ResGlobalInfo>
            <Memberships>
              <Membership ProgramCode="HotelLoyaltyProgram" AccountID="1111111"></Membership>
            </Memberships>
          </ResGlobalInfo>
          <TPA_Extensions>
            <SearchSessionToken>5EA6C45E55104704E4</SearchSessionToken>
          </TPA_Extensions>
        </HotelReservation>
        <TPA_Extensions>
          <NotifyEmails>
            <NotifyEmails>jane.doe@example.com</NotifyEmails>
            <NotifyEmails>arranger@example.com</NotifyEmails>
            <NotifyEmails>manager@example.com</NotifyEmails>
          </NotifyEmails>
          <CustomFields>
            <CustomField Name="trip1" Value="value1t"></CustomField>
            <CustomField Name="trip2" Value="value2t"></CustomField>
            <CustomField Name="user1" Value="value1u"></CustomField>
            <CustomField Name="user2"></CustomField>
          </CustomFields>
        </TPA_Extensions>
      </HotelReservations>
    </OTA_HotelResRQ>
  </Body>
</Envelope>

OTA_HotelResRQ

Name Type Description
HotelReservations complex Required A collection of hotel reservations. SAP Concur will only send one (1) hotel reservation.

HotelReservation

Name Type Description
RoomStays complex Required A reference to identify the booking.
ResGuests complex Required List of guests. Supported value: 1
ResGlobalInfo complex Contains information that affects the reservation as a whole, typically a list of reward programs (see Memberships) or itinerary remarks (see Comments).
TPA_Extensions/SearchSessionToken stringLength1to128 The token obtained from Search response that links the Search results to Availability and Reservation requests.

RoomStays

Name Type Description
RatePlans complex Required Refer to RatePlans in Availability.
Timespan complex Required Refer to Time-span in Availability.
BasicPropertyInfo complex Required See Availability.
Comments complex Comments from the user which are passed on to the hotel.

GuestCounts

Name Type Description
GuestCounts complex Required Please note: this field is currently being discussed with our partners as the plan to remove GuestCounts from OTA_HotelAvailRQ. A recurring element that identifies the number of guests.

GuestCount

Name Type Description
Count integer Required Please note: this element is planned to be removed. A recurring element that identifies the number of guests and ages of the guests. The number of guests. Supported value: 1

RatePlan

Name Type Description
RatePlanID stringLength1to64 A text field used to provide a special ID code that is associated with the rate and is required in the reservation request in order to obtain the rate.
Guarantee complex Required Refer to Guarantee in Availability.

Guarantee

Name Type Description
GuaranteeType stringLength1to32 Required CC/DC/Voucher will be sent if credit card present, None otherwise.
GuaranteesAccepted complex Required Guarantee and payment information.

GuaranteesAccepted

Name Type Description
Default boolean This is to indicate that the information in the model is the default (e.g. if PaymentCard information is completed then this would be considered the default if the boolean is true).
NoCardHolderInfoReqInd boolean If true, no credit card holder information is required. If false, it is required.
NameReqInd boolean If true, the credit card holder name is required. If false, it is not required.
AddressReqInd boolean If true, credit card holder address is required. If false, it is not required.
PhoneReqInd boolean If true, credit card holder phone number is required. If false, it is not required.
InterbankNbrReqInd boolean If true, the credit card interbank number is required. If false, it is not required.
PaymentCard complex Required Specific payment card information.

PaymentCard

Name Type Description
CardCode upperCaseAlphaLength1to2 Issuer code. Example: AX, CA, DC, DS, JC, VI. Map to AMEX, Mastercard, Diners Club, Discover, JCB, Visa
ExpireDate MMYYDate Indicates the ending date.
CardType stringLength1to32 Required Payment card type. Example: MasterCard
CardHolderName stringLength1to32 Required Card holder name.
CardNumber complex Required The card number.
Address complex Required Refer to Address in Search.
SeriesCode complex Verification digits.

SeriesCode

Name Type Description
PlainText stringLength1to32 Required CVV number. Only one (1) element of this type is sent.

Comments

Name Type Description
Comment complex Required SAP Concur will send one Text element per Comment element.

Comment

Name Type Description
Text string Required Text representing the comment.

Text

Name Type Description
TextFormat stringLength1to32 Required Supported value: Plain text

ResGuest

Name Type Description
Profiles complex Required List of Profiles. SAP Concur will only send one (1) profile.

Profile

Name Type Description
Customer complex Required Element to describer a customer.
CompanyInfo complex Element to capture the company name.

Customer

Name Type Description
Gender string Gender. Supported values: Male, Female, Unknown, Male_NoShare, Female_NoShare
BirthDate date Customer's birthday.
PersonName complex Element representing a customer's name.
Telephone complex Element representing a telephone number.
Email stringLength1to128 Email address.
Address complex Refer to Address in Search.
CitizenCountryName complex ISO 3166 representation of the user's country as defined in their SAP Concur Profile.

PersonName

Name Type Description
NamePrefix stringLength1to16 Salutation of honorific. List subject to change. Example values: Mr, Mrs, Ms, Miss, Dr, Rev, Sir, Lord, Lady, Dr Mr, Dr Mrs, Dr Ms, Prof Mr, Prof Mrs, Prof Ms, Prof Dr Mr, Prof Dr Mrs, Prof Dr Ms. Note: Prefixes can be specified in any of the languages supported by Concur Travel.
GivenName stringLength1to64 Given name, first name or names.
Surname stringLength1to64 Required Family name, last name. May also be used for full name if the sending system does not have the ability to separate a full name into its parts. Example: the surname element may be used to pass the full name.

Telephone

Name Type Description
PhoneNumber stringLength1to32 Required A string representing a customer's phone number.

CitizenCountryName

Name Type Description
Code stringLength1to32 Required ISO 3166 country code.

CompanyInfo

Name Type Description
CompanyName stringLength1to32 Required A string representing a customer's company.

ResGlobalInfo

Note: This structure is used in both request and response. Different elements are used in each of them.

Name Type Description
Memberships complex Request Only A collection of memberships. Provides a list of reward programs. Example: loyalty cards
Comments complex Response Only A collection of comments. Provides a list of arbitrary reservation comments. Example: modification code
BasicPropertyInfo complex See Availability.

Memberships

Name Type Description
Membership complex A recurring element that identifies the type of reservation comment.

Membership

Name Type Description
ProgramCode stringLength1to32 Required Always HotelLoyaltyProgram for hotels
AccountID stringLength1to64 Required The account identification number for this particular member in this particular program.

Comments

Name Type Description
Comment complex A recurring element that carries reservation comment. Maximum elements: 9

Comment

Name Type Description
Name stringLength1to64 Attribute containing comment title.
Text string Required Comment payload. Up to 3 Text elements in the comment. Up to 200 characters in the text.

TPA Extensions

Name Type Description
NotifyEmails complex Email address which can be used by the vendor to contact the customer.
CustomFields complex A reference to identify the booking.

NotifyEmails

Name Type Description
NotifyEmails stringLength1to128 Required There will be one (1) NotifyEmails element per email address in the configuration.

CustomFields

Name Type Description
CustomField complex Required A custom field in the form of a key-value pair.

CustomField

Name Type Description
Name stringLength1to32 Required Name of the custom field.
Value stringLength1to32 Value of the custom field.

Response

The maximum allowed size of OTA_HotelResRS is 150 KB. Any response that exceeds this limit shall be dropped.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
  <soap:Body>
    <OTA_HotelResRS xmlns="http://www.opentravel.org/OTA/2003/05" Version="6" ResResponseType="Reserved">
      <Success/>
      <HotelReservations>
        <HotelReservation>
          <UniqueID Type="14" ID="88618333"/>
          <UniqueID Type="1000" ID="12345"/>
          <RoomStays>
            <RoomStay>
              <RatePlans>
                <RatePlan RatePlanID="EZ57LL7">
                  <CancelPenalties CancelPolicyIndicator="true">
                    <CancelPenalty>
                      <PenaltyDescription>
                        <Text>test cancel policy 1</Text>
                      </PenaltyDescription>
                    </CancelPenalty>
                    <CancelPenalty>
                      <PenaltyDescription>
                        <Text>test cancel policy 2</Text>
                      </PenaltyDescription>
                      <PenaltyDescription>
                        <Text>test cancel policy 3</Text>
                      </PenaltyDescription>
                    </CancelPenalty>
                    <CancelPenalty>
                      <Deadline AbsoluteDeadline="2017-01-26T18:00"/>
                    </CancelPenalty>
                  </CancelPenalties>
                </RatePlan>
              </RatePlans>
              <RoomRates>
                <RoomRate>
                  <Rates>
                    <Rate>
                      <Total AmountAfterTax="185.00" AmountBeforeTax="85.00" CurrencyCode="EUR"/>
                    </Rate>
                  </Rates>
                </RoomRate>
              </RoomRates>
              <TimeSpan End="2017-01-27" Start="2017-01-26"/>
              <BasicPropertyInfo HotelCode="50709" HotelName="Alexander Plaza">
                <Address>
                  <AddressLine>Rosenstr. 1</AddressLine>
                  <CityName>Berlin</CityName>
                  <CountryName Code="DEU">Federal Republic of Germany</CountryName>
                  <StateProv StateCode="BE">Berlin District</StateProv>
                  <PostalCode>BE123</PostalCode>
                </Address>
                <ContactNumbers>
                  <ContactNumber PhoneNumber="1111111112" PhoneTechType="1"/>
                </ContactNumbers>
              </BasicPropertyInfo>
            </RoomStay>
          </RoomStays>
          <ResGuests>
            <ResGuest>
              <Profiles>
                <ProfileInfo>
                  <Profile>
                    <Customer>
                      <PersonName>
                        <GivenName>Jane</GivenName>
                        <Surname>Doe</Surname>
                      </PersonName>
                    </Customer>
                  </Profile>
                </ProfileInfo>
              </Profiles>
            </ResGuest>
          </ResGuests>
          <ResGlobalInfo>
            <Comments>
              <Comment Name="First Comment">
                <Text>First line of first comment</Text>
                <Text>Second line of first comment</Text>
              </Comment>
              <Comment>
                <Text>Second comment without name</Text>
              </Comment>
            </Comments>
          </ResGlobalInfo>
        </HotelReservation>
      </HotelReservations>
    </OTA_HotelResRS>
  </soap:Body>
</soap:Envelope>

OTA_HotelResRS

Name Type Description
ResResponseType stringLength1to32 Required See the list of possible values.
HotelReservations complex Required SAP Concur only supports one (1) reservation. All extra reservations will be ignored.

ResResponseType

Value Description
Cancelled The item is cancelled.
Committed The item is reserved.
Unsuccessful -
Reserved The item is reserved.

HotelReservations

Name Type Description
HotelReservation complex Required A reference to identify the booking.

HotelReservation

Name Type Description
UniqueID complex Required A reference to identify the booking. Maximum occurrences: 2
RoomStays complex Required A collection of details on the room stay including time span of this room stay, and financial information related to the room stay, including guarantee, deposit, payment, and cancellation penalties.

UniqueID

Name Type Description
ID stringLength1to32 Required A reference to identify the booking.
Type stringLength1to32 Required A reference to identify the type of UniqueID. See Type.

Type - Possible Values

Value Description
14 Reservation ID used in subsequent calls (Itinerary, Cancel).
15 Cancellation number, displayed in UI, proof of cancellation.
40 Hotel Reservation System Confirmation number (for future use).
1000 Cancellation/modification code. This will be rendered on itinerary page and can be used to change the reservation outside of the SAP Concur system. SAP Concur-specific OTA extension.

RoomStays

Name Type Description
RoomStay complex Required Details on the room stay including time span of this room stay, pointers to res guests, comments and special requests pertaining to this particular room stay. Financial information related to the room stay, including guarantee, deposit, payment, and cancellation penalties.

RoomStay

Name Type Description
RatePlans complex Required A collection of rate plans associated with a particular room stay.
Timespan complex Required Refer to TimeSpan in Availability.
BasicPropertyInfo complex Required See Availability.

RatePlan

Name Type Description
CancelPenalties complex Refer to CancelPenalties in Availability.

RoomRates

Name Type Description
RoomRate complex Required RoomRate used for reservation. SAP Concur only expects one (1) RoomRate.

RoomRate

Name Type Description
Rates complex Required SAP Concur only expects one (1) Rates.

Rates

Name Type Description
Rate complex Required Contains the payment policy for the given room. SAP Concur only expects one (1) Rate.

Rate

Name Type Description
Total complex Required A description of the rate. Refer to Total in Availability.

Message to perform the initial search for hotels.

SOAPAction OTA Name Message Structure
search HotelSearch OTA_HotelSearchRQ

Request

<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
  <Header xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <authentication xmlns="http://www.concur.com/webservice/auth">
      <userid>user</userid>
      <password>password</password>
    </authentication>
  </Header>
  <Body xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <OTA_HotelSearchRQ xmlns="http://www.opentravel.org/OTA/2003/05" EchoToken="test_request_id" Version="4"
                       PrimaryLangID="de" AltLangID="de" MaxResponses="100">
      <POS>
        <Source ISOCurrency="USD">
          <RequestorID Type="1" ID="HTL011235"></RequestorID>
        </Source>
      </POS>
      <Criteria>
        <Criterion>
          <Position Latitude="47.61037" Longitude="-122.20067"></Position>
          <HotelRef HotelName="sunshine"></HotelRef>
          <Radius Distance="5" DistanceMax="30" UnitOfMeasureCode="1"></Radius>
          <StayDateRange Start="2018-09-26" End="2018-09-27"></StayDateRange>
        </Criterion>
      </Criteria>
      <TPA_Extensions>
        <CustomFields>
          <CustomField Name="OrgUnit" Value="Travel Agents"></CustomField>
        </CustomFields>
      </TPA_Extensions>
    </OTA_HotelSearchRQ>
  </Body>
</Envelope>

OTA_HotelSearchRQ

Name Type Description
MaxResponses integer Required SAP Concur currently supports 100 search results in one (1) message. If more than 100 results are returned SAP Concur drops all results after the 100th entry.
Criteria complex Required Specified hotel search criteria.
TPA_Extensions complex This adds an Org Unit name to the Search request.

Criteria

Name Type Description
Criterion complex Required Child elements that identify a single search criterion by criteria type.

Criterion

The criterion is used to define the search criteria. Currently we support only one Criterion.

Name Type Description
Position complex Required for Search request only, but optional for Availability request. Used to specify the geographic coordinates of a location, expressed in notation specified by ISO standard 6709.
HotelRef complex Indicates the detail of hotel reference information.
Radius complex Used to specify the extent of a search area. The extent is relative to an element (position, address, hotelRef, etc.) present in this ItemSearchCriterionType that specifies a location.
StayDateRange complex Required Range of dates using ISO 8601.

TPA_Extensions

Name Type Description
CustomFields complex This adds Org Unit name.

CustomFields

Name Type Description
CustomField - -
Name xs:string -
Value xs:string -

Position

Name Type Description
Latitude stringLength1to16 Required The measure of the angular distance on a meridian north or south of the equator.
Longitude stringLength1to16 Required The measure of the angular distance on a meridian east or west of the prime meridian.

HotelRef

Name Type Description
HotelName stringLength1to128 A text field used to communicate the proper name of the hotel.

Radius

The radius element is used along with the Hotel Preference to categorize the search results.

Name Type Description
Distance stringLength1to16 Required The distance from a reference point.
DistanceMax stringLength1to16 Attribute indicating the distance from a reference point or Preferred (Corporate) hotels.
UnitOfMeasureCode stringLength1to16 Required The unit of measure in a code format. Refer to OpenTravel Code List of Measure Code (UOM). SAP uses 1 for miles, 2 for kilometers.

StayDateRange

Name Type Description
Start date, time, or datetime Required The starting value of the time span.
End date, time, or datetime Required The ending value of the time span.

Response

The maximum allowed size of OTA_HotelSearchRS is 1 MB. Any response that exceeds this limit will be dropped.

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
  <soap:Body>
    <OTA_HotelSearchRS xmlns="http://www.opentravel.org/OTA/2003/05" AltLangID="EN" PrimaryLangID="EN" Version="4">
      <Success/>
      <Properties>
        <Property ChainCode="HI" ChainName="Holiday Inn" HotelCode="22222" HotelName="Holiday Inn Express Sunshine">
          <Position Latitude="47.61038" Longitude="-122.20068"/>
          <Address>
            <AddressLine>99 East 27th Street</AddressLine>
            <CityName>Bellevue</CityName>
            <PostalCode>98009</PostalCode>
            <StateProv StateCode="WA">Washington</StateProv>
            <CountryName Code="US">United States of America</CountryName>
          </Address>
          <ContactNumbers>
            <ContactNumber PhoneNumber="+14255551234" PhoneTechType="1"/>
          </ContactNumbers>
          <Award Rating="4"/>
          <HotelAmenity Code="173"/>
          <HotelAmenity Code="255"/>
          <TPA_Extensions>
            <HotelPreference>not_preferred</HotelPreference>
            <TPA_HotelPreviewImageURI>
              <URL>https://production.example.com/hotel-image.jpg</URL>
            </TPA_HotelPreviewImageURI>
            <TPA_PropertyReferenceInfo>
              <PropertyReference ReferenceCatalogCode="1376249" ReferenceCatalogName="giata"/>
            </TPA_PropertyReferenceInfo>
          </TPA_Extensions>
        </Property>
      </Properties>
      <TPA_Extensions>
        <SearchSessionToken>5EA6C45E55104704E4</SearchSessionToken>
      </TPA_Extensions>
    </OTA_HotelSearchRS>
  </soap:Body>
</soap:Envelope>

OTA_HotelSearchRS

Name Type Description
Properties complex Required A collection of individual property information.
TPA_Extensions/SearchSessionToken stringLength1to128 Optional A token that links the Search results to Availability and Reservation requests.

Properties

Name Type Description
Property complex Required A property that matches some or all of the search criteria.

Property

Name Type Description
ChainCode stringLength1to8 2-letter valid GDS chain code. The code that identifies a hotel chain or management group. Must be present to support filtering, preferences or travel rules base on chains
ChainName stringLength1to64 The name of the hotel chain. Examples: Hilton, Marriott, Hyatt, Starwood
HotelCode stringLength1to16 Required The code that uniquely identifies a single hotel property. Used in other OTA messages.
HotelName stringLength1to128 Required A text field used to communicate the proper name of the hotel.
Position complex Required Refer to Position in the Request.
Address complex Required Public address of the hotel property.
ContactNumbers complex Property contact numbers.
Award complex An element that identifies the hotel rating.
HotelAmenity complex List of hotel amenities.
TPA_Extensions complex SAP Concur-specific extension of OTA spec. This adds support for extra property fields.

Address

Name Type Description
AddressLine stringLength1to255 The street name and number. Maximum occurrences: 5
CityName stringLength1to64 Name of the city.
PostalCode stringLength1to16 The postal code.
StateProv complex Name of the state.
CountryName complex Country name. Example: Ireland

StateProv

Name Type Description
StateCode stringLength0to64 The standard code or abbreviation for the state, province, or region (note the code may not be available for all states).

CountryName

Name Type Description
Code stringLength0to64 Required The name or ISO 3166 code of a country.

ContactNumbers

Name Type Description
ContactNumber complex Element which contains the ContactNumber. SAP Concur only accepts the first (1) ContactNumber of each supported type.

ContactNumber

Name Type Description
CountryAccessCode stringLength1to32 The country code.
PhoneNumber stringLength1to32 Required The phone number.
PhoneTechType string SAP Concur currently only supports a PhoneTechType set to 1 (phone) or 3 (fax). You can omit this field only in case you are providing one contact number. We suggest to fill the type in all cases, it may become mandatory in the future.

Award

Name Type Description
Rating integer Required Hotel rating should be an integer number from 0 to 5, representing its star rating. A rating value of 0 will be ignored and treated as N/A.

HotelAmenity

Name Type Description
Code string Refer to Supported Hotel Amenities

Supported Hotel Amenities

Code Description
173 Breakfast
255 Broadband Internet
228 Business Center
215 Convention Center
96 Dry Cleaning
48 Fitness Center
44 Game Room
236 Golf Course
54 Indoor Pool
289 Kids Activities
269 Meeting Rooms
198 Non-smoking Rooms
66 Outdoor Pool
224 Pets Allowed
76 Restaurant
71 Swimming Pool
233 Tennis Court
101 Wheelchair Accessible

TPA Extensions

Name Type Description
HotelPreference stringLength1to32 Required SAP Concur allows customers to override property preference in the system settings. Supported values: not_preferred, less_preferred, preferred, most_preferred
TPA_HotelPreviewImageURI complex Required Details for an image of a given category.
TPA_PropertyReferenceInfo complex Alternate property ID. Required for Corporate Discount Note support

TPA_HotelPreviewImageURI

Name Type Description
URL string Required Contains an HTTPS URL pointing to a .png or .jpg hotel image file. SAP Concur supports one image URL in the Search Response. For the ability to display more images refer to Descriptive Info message. The image will be used as a thumbnail and should be limited to 70x70 pixels to prevent image artifacts by scaling.

TPA_PropertyReferenceInfo

Name Type Description
ReferenceCatalogName string Required which catalog the property reference comes from. Support giata only for now
ReferenceCatalogCode string Required alternate property id (only giata id of hotel for now) from specified reference catalog

Direct Connect - Hotel v2 - Update History

History of changes in HS2 developer documentation

Date of Change Description
July 22, 2021 Remove references to RefPoint in the Search criteria, it is not used.
July 21, 2021 Removing required tag on Avail/RequireSeriesCode. Removing mention of RequireSeriesCode on RateDetails.
June 23, 2021 More details on ReadItin response and fix to Rate/ExpireDate on RateDetails.
May 17, 2021 Update description for Reservation response confirmation number of type 40 to specify Hotel reservation number.
May 7, 2021 Add response time and content length expectations to Intro page. Add RequestorID to examples for consistency.
Apr 23, 2021 Correcting examples to remove elements/attributes that are not supported. Adding clarification for Reservation.PersonName.NamePrefix. Adding examples of usage for StateProv element. Clarifying expectations for imageURLs in Seach and DescriptiveInfo
Mar 19, 2021 Remove mention of content not being accessible to mobile app. Correction to Availability RoomTypes description. Correction to RoomDescription to indicate multiple text elements are accepted. Removed mention of offset attribute as option for AbsoluteDeadline
Mar 16, 2021 Clarify what value is sent in GuaranteeType in Reservation Request
Feb 16, 2021 New node TPA Property Reference Info added to the Search Response. Description update to clarify that what value is sent in HotelLoyaltyProgram is always sent as ProgramCode in Memberbship
Feb 8, 2021 Remove PaymentPolicies in Reservation Response. Change type Text to string in Descriptive Information Response. Change type and description of Text under RatePlanDescription in Availability and Rate Details Response.
Jan 29, 2021 Clarify NamePrefix in Reservation Request. Make PaymentPolicies in Reservation Response optional
Jan 27, 2021 Update Deadline under CancelPenalty to optional node. Update AbsoluteDeadline attribute under Deadline to required. Update type of URL in TPA_HotelPreviewImageURI to string.
Jan 11, 2021 formattedText type is replaced with string. No longer accepts Deadline node under Guarantee in Availability and Rate Details. Updated ImageFormat's URL type. Updated RateId and RatePlanId type. Added description of RoomRates in Reservation. AmountBeforeTax is now optional in Availability and Rate Details.
Dec 15, 2020 Added BasicPropertyInfo and Timespan to Reservation Response Docs
Dec 4, 2020 Clarification of NoCancelInd and Absolute Deadline in CancelPenalty, Rate-Details and Availability

Direct Connect - Hotel v2 - Use Cases

Basic scenario encompassing all the functionality provided by Hotel Service 2 incorporated into Concur Travel starting from a hotel search, through to confirmation of a booking and ending with a cancellation.

Actors

  1. Primary Actor - Business traveler
  2. Secondary Actor - Hotel Supplier

Use Case

  1. Business traveler performs a search for hotels given a criteria.

  2. The UI displays the available hotels. The business traveler can then select a hotel with visible rates or request to View Rooms in case they are not present. The Business traveler selects a hotel with rates.

  3. The UI displays all available rates for the chosen hotel. The Business user can see the Cancellation Policy. The business traveler clicks on Hotel Details.

  4. The UI displays the hotel details including a long description. The Business traveler closes the Hotel Details pop-up

  5. The UI displays all available rates for the chosen hotel. The business traveler clicks on Rules and Cancellation Policy.

  6. The UI displays the Rules and the Cancellation Policy for the chosen hotel. The Business Travel closes the Rules and Cancellation Policy pop-up.

  7. The UI displays all available rates for the chosen hotel. The Business traveler selects the top most rate. The Trip Summary page is displayed where the Business traveler can set the Hotel Preferences, Enter Guest information (from their profile), select the method of payment and view the total estimated price. The Business traveler agrees to the hotel's rate rules, restrictions and cancellation policy and clicks Reserve Hotel and Continue.

  8. The UI shows the Trip Details page where the Business traveler can add items to their itinerary and review the current itinerary. The Business traveler clicks Next.

  9. The UI shows the Trip Booking Information page where the Business traveler can add trip details. The Business traveler clicks Next.

  10. The UI shows the Trip Confirmation page where the Business traveler can confirm the booking on cancel it. The Business traveler clicks Confirm Booking.

  11. The UI shows the Finished page where the Business traveler can review the trip overview and see the confirmation number along with the trip locator.

  12. The Business user can view the trip in the Upcoming Trips tab on the main Travel page. The Business traveler clicks on the Trip name.

  13. The UI shows the Trip Overview page. The Business traveler chooses the cancel the hotel reservation, by clicking cancel.

  14. The UI shows the Cancel Trip pop-up where the Business traveler may chooser to enter a comment. The Business traveler clicks OK.

  15. The UI shows the Rules and cancellation policy. The Business traveler accepts the policies by checking the 'I agree ...' button and clicking Continue

  16. The UI shows the trip cancellation page where confirmation and cancellation numbers can be found. The Business traveler closes the pop-up.

Search Criteria

Given the following example:

<RadiusDistance="5" DistanceMax="30" UnitOfMeasureCode="2">

Out of 100 returned hotels in response from the Hotel Supplier first 10 hotels are Most Preferred hotels within the 30km radius. The next 10 hotels are Preferred hotels from 30km radius. The remaining 80 hotels are hotels with no preference within the 5km radius. Note: The preference level is defined by the HotelPreference element in the TPA_Extensions, which is outlined in Search.

Reservation and Read Requests

SAP Concur will follow up a Reservation Request with a Read request as soon as possible after processing the Reservation Response. If a Read request does not arrive within 5 minutes for a given Reservation, then the supplier should treat that Reservation as an orphan and should thus seek to cancel it.

General System Overview

./media/image1.png

Direct Connect - Hotel v2 - Virtual Payment Solution

The goal of this document is to establish the flow for virtual / alternative payment methods in conjunction with booking hotels via Concur’s hotel API (HS2). While doing so, it seeks to minimize complexity of implementation that often arises when configuration work needs to be done on both ends (Concur and supplier side). Since the payment solution is typically handled on suppliers’ side, the supplier should control which form of payment will be made available in Concur for each specific client and property by passing the form of payment to Concur. Concur will then offer the accepted payment method to users in the booking flow.

SETUP ON HOTEL SUPPLIER SIDE

The payment agreement is typically made with the hotel supplier. There are multiple potential options which could be:

All mentioned payment methods are normally set up on hotel supplier side to ensure the payment method will be part of the reservation to the hotel and to guarantee acceptance at the hotel. Furthermore, the hotel supplier takes care of invoicing.

SETUP ON CONCUR SIDE

To make sure that the user can use the payment option that is set up on hotel supplier side the client needs to be identified at hotel supplier side. This happens with a client ID (Requestor ID). Requestor ID needs to be set up in Concur on a company (configuration) level.

BOOKING FLOW

1. Search request

Requestor ID is sent with OTA_HotelSearchRQ. Requestor IDs can only be supported on travel configuration level.

2. Response from hotel supplier in OTA_HotelAvailRS

Virtual payment will be marked by the hotel supplier under Concur’s Availability endpoint, OTA_HotelAvailRS (as documented in the SAP Concur Developer Center for Direct Connect: Hotel Service 2). The element to be used will be ‘GuaranteeType’ and its value should be set to ‘none’.

3. Display of payment options in Concur on Review and Reserve page

When guarantee type is set to ‘none’ the FOP selection will not be triggered in the Review and Reserve page, allowing the user to proceed with the reservation without having to specify a payment method.

./media/image1.png

4. Descriptive Billing Data

For Company Account payment or virtual payment, descriptive billing data is required. Descriptive billing data is typically profile data (e.g. cost center or employee ID) or custom trip fields (e.g. project number). Those fields need to be mapped to reference data fields in Concur so that it can be sent to the hotel supplier with the reservation. In order to have this data passed in the reservation request, it is required to have them displayed at the start of booking. Descriptive billing data can be transmitted independently from the payment solution set up at hotel supplier. The field names can be individually defined by HotelService supplier. A client individual naming of custom fields will not be supported.

Org units can also be integrated in this workflow. If enabled, they will be made available through our OTA_HotelSearchRQ and OTA_HotelResRQ call.

5. Reservation

After the user has selected a rate with GuaranteeType marked as ‘none’ the reservation request will be sent with OTA_HotelResRQ. The OTA_HotelResRQ also contains descriptive billing information.

Direct Connect - Hotel v2 - XSD schema

Current xsd schema for Hotel Service 2

HotelService2.xsd

ESS

Event Subscription Service v4

ESS Overview

The Event Subscription Service (ESS) implements the Publish/Subscribe pattern using principles of Event Driven Architecture in the SAP Concur platform. It allows clients and partners to be notified through web services when certain actions take place in connected companies. When the business/system event occurs ESS sends that event to the configured endpoint with relevant information.

In order to begin receiving events, you must first subscribe to the relevant topic(s) for your application. To subscribe to an event, you must work with your relevant SAP Concur technical contact; for partners, please work with your technical enablement contact. For customers, your web services consultant will subscribe on your behalf to the relevant topic(s).

Scope Usage

There are two levels of scopes required for creating subscription.

Name Description Endpoint
events.topic.read Access to ESS API GET, POST, PUT, DELETE
%topic scope% Access to specific topic (events) GET, POST, PUT, DELETE

Process Flow

Process flow for ESS

Access Control

ESS requires a caller to have a proper JWT and scopes, for more details please see the Scopes documentation. A caller must have the following types of scopes:

All required scopes can be requested for a caller application by Partner Enablement team.

ESS Delivery Model

It is important to remember that ESS doesn't have an API that you can call for events, ESS delivers events to your endpoint.

Endpoint Requirements

ESS guarantees at least once event delivery. This is accomplished through the retry posting the event payload to the subscribers' endpoint until the response indicates successful receipt. The expected maximum acknowledgment time for a request to the subscribers' endpoint is 30 seconds. The service will attempt posting to the endpoint and then hold and retry until the subscriber endpoint responds with delivered or not accepted. The service will retry at least 3 days and skip to the next event after unsuccessful delivery.  We suggest that the subscriber consider following:

ESS Authentication

There are several ways that you can be sure that your endpoint being accessed by our service.

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAxS1LsXrEWEEMPooLHa4r
osCAnmkO3HaBAk0YcsDMR6hQeuQNLqRWP65TpbfTbKWmZ22Hzep3Ekhs1qvSZgI+
iq/bnVeDhkcD+LqVQGP+7fyE0E0bO96FOzMmtbRet4wAiiE9+uw5GmZfg+fRG3yI
y2N5u5p7VHJ1RwNugrIUQjhrLvZc+lhqR/aKTxQCQ5CGAgLZIcr3FIWCWrSBMK3d
Wy3KI+qe3ZX0STrCCNxl2UFnuuAa2RZZ2j4QtWHlNkyK+UEup+cGkvpc1XrT7anL
HlbTP6jE7MqB5sJ9r2EEzrJzJZjD13UqlzvI61tTC8SKpuk5AEaSsUV7RKlKUCjB
8wIDAQAB
-----END PUBLIC KEY-----

ESS Behavior

The Event Subscription service has the following characteristics from the subscriber perspective:

EXPENSE

Allocations

The SAP Concur Allocations API allows for the retrieval of allocation information as it relates to a Report ID, Entry ID, or Itemization ID. Using this API allows for an in-depth review of Expense Report Data and how that data has been allocated in SAP Concur. The Allocations API allows for the programmatic gathering of details on how the expense report data was allocated by the report owner, making it ideal for Data Gathering, Expense Reporting, and Validations.

Version

3.0

Retrieve All Allocations Per Entry or Report

GET /api/v3.0/expense/allocations

Parameters

Name Type Format Description
limit Int32 query The number of records to return. The default is 25 and the maximum is 100.
offset string query The starting point of the next set of results, after the limit specified in the limit field has been reached.
reportID string query The unique identifier for the report as it appears in the Concur Expense UI. Format: A variable-length string. Maximum length: 32 characters.
entryID string query The unique identifier for the expense entry.
itemizationID string query The unique identifier for the expense itemization.

Note: userId is not a supported query string parameter for this API.

Request URL

https://www.concursolutions.com/api/v3.0/expense/allocations?limit=10

JSON Example of a Successful Response

{
  "Items": [
    {
      "EntryID": "gWidFO7ikXSy7gHnNngC12jkL7khMiREv4g",
      "Percentage": "100.00000000",
      "IsPercentEdited": false,
      "IsHidden": true,
      "AccountCode1": "1",
      "AccountCode2": null,
      "Custom1": null,
      "Custom2": null,
      "Custom3": null,
      "Custom4": null,
      "Custom5": null,
      "Custom6": null,
      "Custom7": null,
      "Custom8": null,
      "Custom9": null,
      "Custom10": null,
      "Custom11": null,
      "Custom12": null,
      "Custom13": null,
      "Custom14": null,
      "Custom15": null,
      "Custom16": null,
      "Custom17": null,
      "Custom18": null,
      "Custom19": null,
      "Custom20": null,
      "ID": "gWmudeHM8AuFikny3Hrpz$s2gaNvc0E7Xfyw",
      "URI": "https://www.concursolutions.com/api/v3.0/expense/allocations/gWmudeHM8AuFikny3Hrpz$s2gaNvc0E7Xfyw"
    },
    {
      "EntryID": "gWidFO7ikXSy41$smPkwdC5cL1aku$pSgc$p4g",
      "Percentage": "100.00000000",
      "IsPercentEdited": false,
      "IsHidden": true,
      "AccountCode1": "1",
      "AccountCode2": null,
      "Custom1": null,
      "Custom2": null,
      "Custom3": null,
      "Custom4": null,
      "Custom5": null,
      "Custom6": null,
      "Custom7": null,
      "Custom8": null,
      "Custom9": null,
      "Custom10": null,
      "Custom11": null,
      "Custom12": null,
      "Custom13": null,
      "Custom14": null,
      "Custom15": null,
      "Custom16": null,
      "Custom17": null,
      "Custom18": null,
      "Custom19": null,
      "Custom20": null,
      "ID": "gWmudeHM8AuFhxez1E72ExJPksvTH0KPPyw",
      "URI": "https://www.concursolutions.com/api/v3.0/expense/allocations/gWmudeHM8AuFhxez1E72ExJPksvTH0KPPyw"
    }
  ]
}

Response

Allocations Schema

Retrieve a Single Allocation by ID

GET /api/v3.0/expense/allocations/{id}

Parameters

Name Type Format Description
id string path Required The unique identifier for the allocation.
user string query The login ID of the user who owns the allocation. The user must have the Web Services Admin role to use this parameter.

Schema

Allocations

Name Type Format Description
Items array Allocation The result collection.
NextPage string - The URI of the next page of results, if any.

Allocation

Name Type Format Description
AccountNumber string - The primary accounting code assigned to the expense type associated with this allocation. Typically, expense types have only a primary account code.
AccountCode2 string - The secondary or alternative accounting code assigned to the expense type associated with this allocation.
Custom1 through Custom20 CustomFieldExtension - A custom field associated with the allocation. This field may or may not have data, depending on how Expense is configured. Format: Text field. Maximum length: 64 characters.
EntryID string - The unique identifier for the expense entry.
ID string - The unique identifier of the resource.
IsHidden Boolean - Indicates whether the allocation is hidden. Format: true or false
IsPercentEdited Boolean - Indicates whether the percentage has been edited. Format: true or false
Percentage string - The percentage of the expense that is included in this allocation.
URI string - The URI to the resource.

Custom Field

Name Type Format Description
Code string - For list fields, this is the list item code.
Label string - The label value for the custom field.
ListItemID string - For list fields, this is the list item ID.
Sequence integer - The sequence value for this custom field i.e. the order in which this field appears on the form.
Type string - The custom field type. Possible values: Amount, Boolean, ConnectedList, Date, Integer, List, Number, Text
Value string - The value in the Org Unit or Custom field. For list fields, this is the name of the list item. Maximum length: 48 characters

Request URL

https://www.concursolutions.com/api/v3.0/expense/allocations/gWmudeHM8AuFlD9Py%24p7cwkclNQvGC1JQPyw

JSON Example of a Successful Response

{
  "EntryID": "gWidFO7ikXSy8HdaIfw32sJhcmk76TjD$p4g",
  "Percentage": "100.00000000",
  "IsPercentEdited": false,
  "IsHidden": true,
  "AccountCode1": "1",
  "AccountCode2": null,
  "Custom1": null,
  "Custom2": null,
  "Custom3": null,
  "Custom4": null,
  "Custom5": null,
  "Custom6": null,
  "Custom7": null,
  "Custom8": null,
  "Custom9": null,
  "Custom10": null,
  "Custom11": null,
  "Custom12": null,
  "Custom13": null,
  "Custom14": null,
  "Custom15": null,
  "Custom16": null,
  "Custom17": null,
  "Custom18": null,
  "Custom19": null,
  "Custom20": null,
  "ID": "gWmudeHM8AuFlD9Py$p7cwkclNQvGC1JQPyw",
  "URI": "https://www.concursolutions.com/api/v3.0/expense/allocations/gWmudeHM8AuFlD9Py$p7cwkclNQvGC1JQPyw"
}

Attendee Types v3

The Attendee Type resource represents the type of attendee as configured in Concur.

Version

3.0

Attendee Types v1 (Deprecated)

Retrieve all attendees types

GET  /api/v3.0/expense/attendeetypes/

Parameters

Name Type Format Description
offset string query The starting point of the next set of results, after the limit specified in the limit field has been reached.
limit Int32 query The number of records to return. Default value: 25

Request URL

https://www.concursolutions.com/api/v3.0/expense/attendeetypes?limit=10

JSON example of a successful response

{
  "Items": [
    {
      "Name": "Business Guest",
      "Code": "BUSGUEST",
      "AttendeeFormID": "gWvidmKNPVEaOg$s66rqA62OJVXfvHBMs4sw",
      "DuplicateSearchFields": [
        "Title",
        "Company",
        "OwnerEmpName",
        "FirstName",
        "LastName"
      ],
      "ConnectorID": "",
      "AllowManuallyEnteredAttendees": true,
      "AllowAttendeeCountEditing": true,
      "ID": "gWjUHBxUY4iQLA9KTkbtUD6pc",
      "URI": "https://www.concursolutions.com/api/v3.0/expense/attendeetypes/gWjUHBxUY4iQLA9KTkbtUD6pc"
    },
    {
      "Name": "Healthcare Professional",
      "Code": "HCP",
      "AttendeeFormID": "gWvidmKNPVEH7wO$pDpD9$pk6xVlyJ4EjwIdA",
      "DuplicateSearchFields": [
        "Title",
        "Custom18",
        "ExternalId",
        "FirstName",
        "LastName",
        "Custom7",
        "Custom14",
        "Custom15",
        "Custom16",
        "Custom17",
        "Custom19",
        "Custom8",
        "Custom20"
      ],
      "ConnectorID": "",
      "AllowManuallyEnteredAttendees": true,
      "AllowAttendeeCountEditing": false,
      "ID": "gWjYOjoOorT3dhpHGto5H$poJuoa0m",
      "URI": "https://www.concursolutions.com/api/v3.0/expense/attendeetypes/gWjYOjoOorT3dhpHGto5H$poJuoa0m"
    }
  ]
}

Retrieve attendee types by ID

GET  /api/v3.0/expense/attendeetypes/{id}

Parameters

Name Type Format Description
id string path Required The ID of the attendee type.

Request URL

https://www.concursolutions.com/api/v3.0/expense/attendeetypes/gWjYOjoOorT3dhpHGto5H%24poJuoa0m

JSON example of a successful response

{
  "Name": "Healthcare Professional",
  "Code": "HCP",
  "AttendeeFormID": "gWvidmKNPVEH7wO$pDpD9$pk6xVlyJ4EjwIdA",
  "DuplicateSearchFields": [
    "Title",
    "Custom18",
    "ExternalId",
    "FirstName",
    "LastName",
    "Custom7",
    "Custom14",
    "Custom15",
    "Custom16",
    "Custom17",
    "Custom19",
    "Custom8",
    "Custom20"
  ],
  "ConnectorID": "",
  "AllowManuallyEnteredAttendees": true,
  "AllowAttendeeCountEditing": false,
  "ID": "gWjYOjoOorT3dhpHGto5H$poJuoa0m",
  "URI": "https://www.concursolutions.com/api/v3.0/expense/attendeetypes/gWjYOjoOorT3dhpHGto5H$poJuoa0m"
}

Create a new attendee type

DEPRECATED: 05/19/2016 UNSUPPORTED: 11/19/2016

POST  /api/v3.0/expense/attendeetypes

Parameters

Name Type Format Description
content - body Required The AttendeeType object to create.

Input

Attendee Schema

Response

Attendee Schema

Request URL

https://www.concursolutions.com/api/v3.0/expense/attendeetypes

JSON example of a successful response

{
  "ID": "gWjYOj4JuT5VB$paQnF31149$sKgaM$p",
  "URI": "https://www.concursolutions.com/api/v3.0/expense/attendeetypes/gWjYOj4JuT5VB$paQnF31149$sKgaM$p"
}

Update existing attendee type

PUT  /api/v3.0/expense/attendeetypes/{id}

Parameters

Name Type Format Description
id string path Required The ID of the attendee type.
content - body Required The partial or complete Attendee object to update.

Input

Attendee Schema

Response

Attendee Schema

Request URL

https://www.concursolutions.com/api/v3.0/expense/attendeetypes/gWjYOjoa7Fe0HsTGEk417OCzqUf1A

Delete an attendee type

DEPRECATED: 05/19/2016 UNSUPPORTED: 11/19/2016

DELETE  /api/v3.0/expense/attendeetypes{id}

Parameters

Name Type Format Description
id string path Required The ID of the attendee type to delete

Input

Attendee Schema

Response

Attendee Schema

Request URL

https://www.concursolutions.com/api/v3.0/expense/attendeetypes/gWjYOjomP3Jxp6dFC%24pIg%24sc99nQQ3q

Schema

Attendee Type

Name Type Format Description
AllowAttendeeCountEditing boolean - Determines whether users are allowed to edit the count for this attendee type. Format: true or false
AllowManuallyEnteredAttendees boolean - Determines whether users are allowed to add attendees for this attendee type. Format: true or false
AttendeeFormID string - The unique identifier for the attendee form for this attendee type.
Code string - A code that indicates the type of attendee. Examples: EMPLOYEE, SPOUSE, BUSGUEST. Maximum length: 40 characters
ConnectorID string - The unique identifier for the Application Connector that is the data source for this attendee type. When this field is empty, the Expense database is the data source.
DuplicateSearchFields Array AttendeeType The list of Attendee field IDs used by the Add Attendee user interface to alert users that the attendee they want to add is a possible duplicate. This parent element has a DuplicateSearchField child element for each field ID.
ID string - The unique identifier of the resource.
Name string - The name for the attendee type. This name must be unique. Maximum length: 40 characters
URI string - The URI to the resource.

Attendees v3

Retrieve all attendees owned by the specified user

Request

URI

Template
GET /api/v3.0/expense/attendees
Parameters
Name Type Format Description
externalID string query The external ID of an attendee. By entering a value for this parameter, you can limit the results to the attendees who match the specified external ID. Up to 10 comma-separated external IDs may be specified.
attendeeTypeID string query The ID of an attendee type. By entering a value for this parameter, you can limit the results to the attendees who match the specified type.
offset string query The starting point of the next set of results, after the limit specified in the limit field has been reached.
limit Int32 query The number of records to return. Default value: 25
user string query The login ID of the user that has added the attendee to an expense. The user who is performing this API request must have the Web Services Admin (Professional) or Can Administer (Standard) user role to use this parameter

Payload

None

Response

Payload

Example

Request

GET https://www.concursolutions.com/api/v3.0/expense/attendees?limit=15

Response

{
  "Items": [
    {
      "AttendeeTypeCode": "NOSHOWS",
      "AttendeeTypeID": "gWjYOjoCmOo2Ua$pH4qnCsQxgS8Z0E",
      "FirstName": null,
      "LastName": "No Show Attendee",
      "MiddleInitial": null,
      "Suffix": null,
      "Company": null,
      "Title": null,
      "ExternalID": null,
      "HasExceptionsPrevYear": false,
      "HasExceptionsYTD": false,
      "TotalAmountPrevYear": 0,
      "TotalAmountYTD": 0,
      "VersionNumber": 1,
      "OwnerName": "System, Concur",
      "OwnerLoginID": "ConcurSystem",
      "CurrencyCode": "USD",
      "Custom1": null,
      "Custom2": null,
      "Custom3": null,
      "Custom4": null,
      "Custom5": null,
      "Custom6": null,
      "Custom7": null,
      "Custom8": null,
      "Custom9": null,
      "Custom10": null,
      "Custom11": null,
      "Custom12": null,
      "Custom13": null,
      "Custom14": null,
      "Custom15": null,
      "Custom16": null,
      "Custom17": null,
      "Custom18": null,
      "Custom19": null,
      "Custom20": null,
      "Custom21": null,
      "Custom22": null,
      "Custom23": null,
      "Custom24": null,
      "Custom25": null,
      "ID": "gWj3IHRYiHZGUtIO83ILhbNHqCsjMmkvj$pQ",
      "URI": "https://www.concursolutions.com/api/v3.0/expense/attendees/gWj3IHRYiHZGUtIO83ILhbNHqCsjMmkvj$pQ"
    }
  ]
}

Retrieve a single attendee by ID

Request

URI

Template
/api/v3.0/expense/attendees/{id}
Parameters
Name Type Format Description
id string path Required The attendee object to create.
user string query The login ID of the user that has added the attendee to an expense. The user who is performing this API request must have the Web Services Admin (Professional) or Can Administer (Standard) user role to use this parameter

Payload

None

Response

Payload

Example

Request

GET https://www.concursolutions.com/api/v3.0/expense/attendees/gWj3IHRYiHZGd0HJy%24p5Uk0zITlsMX0ymT%24pA

Response

{
  "AttendeeTypeCode": "PRIVATE",
  "AttendeeTypeID": "gWjYOjoa7Fe0HsTGEk417OCzqUf1A",
  "FirstName": "Diego",
  "LastName": "Rodriguez",
  "MiddleInitial": null,
  "Suffix": null,
  "Company": "Contoso",
  "Title": null,
  "ExternalID": "1",
  "HasExceptionsPrevYear": false,
  "HasExceptionsYTD": false,
  "TotalAmountPrevYear": 0,
  "TotalAmountYTD": 0,
  "VersionNumber": 1,
  "OwnerName": "System, Concur",
  "OwnerLoginID": "ConcurSystem",
  "CurrencyCode": "USD",
  "Custom1": null,
  "Custom2": null,
  "Custom3": null,
  "Custom4": null,
  "Custom5": null,
  "Custom6": null,
  "Custom7": null,
  "Custom8": null,
  "Custom9": null,
  "Custom10": null,
  "Custom11": null,
  "Custom12": null,
  "Custom13": null,
  "Custom14": null,
  "Custom15": null,
  "Custom16": null,
  "Custom17": null,
  "Custom18": null,
  "Custom19": null,
  "Custom20": null,
  "Custom21": null,
  "Custom22": null,
  "Custom23": null,
  "Custom24": null,
  "Custom25": null,
  "ID": "gWj3IHRYiHZGd0HJy$p5Uk0zITlsMX0ymT$pA",
  "URI": "https://www.concursolutions.com/api/v3.0/expense/attendees/gWj3IHRYiHZGd0HJy$p5Uk0zITlsMX0ymT$pA"
}

Create a new attendee

Request

URI

Template
/api/v3.0/expense/attendees
Parameters
Name Type Format Description
user string query The login ID of the user that has added the attendee to an expense. The user who is performing this API request must have the Web Services Admin (Professional) or Can Administer (Standard) user role to use this parameter

Payload

Response

Payload

Example

Request

POST https://www.concursolutions.com/api/v3.0/expense/attendees

Response

{
  "ID": "gWj3IHRYiHZOQ2T9NNdJ$plN$s7$sG8LhZwjoQ",
  "URI": "https://www.concursolutions.com/api/v3.0/expense/attendees/gWj3IHRYiHZOQ2T9NNdJ$plN$s7$sG8LhZwjoQ"
}

Update existing attendees

Request

URI

Template
/api/v3.0/expense/attendees/{id}
Parameters
Name Type Format Description
id string path Required The attendee ID
user string query The login ID of the user that has added the attendee to an expense. The user who is performing this API request must have the Web Services Admin (Professional) or Can Administer (Standard) user role to use this parameter

Payload

Response

Payload

Example

Request

PUT https://www.concursolutions.com/api/v3.0/expense/attendees/gWj3IHRYiHZOQ2T9NNdJ%24plN%24s7%24sG8LhZwjoQ

Response

ToDo

Schema

Attendees

Name Type Format Description
Items array Attendee The result collection.
NextPage string - The URI of the next page of results, if any.

Attendee

Name Type Format Description
AttendeeTypeCode string - A code that indicates the type of attendee. Examples: EMPLOYEE, SPOUSE, BUSGUEST. Maximum length: 40 characters
AttendeeTypeID string - The ID of the attendee type. To obtain the attendee type ID value, use the GET /expense/attendeetypes endpoint. The value of the ID element in the response is the attendee type ID.
Company string - The name of the attendee's company. Maximum length: 150 characters
CurrencyCode string - The 3-letter ISO 4217 currency code for monetary amounts related to an attendee.
Custom1 through Custom25 CustomField - A custom field associated with the attendee. This field may or may not have data, depending on how Expense is configured.
ExternalID string - A unique identifier for the attendee, assigned outside of Concur. Maximum length: 48 characters NOTE: For HCP connectors where information returned to Concur represents one record per attendee+address pair, this value should be a unique identifier for that pair, and the unique identifier for the individual should be placed into a custom field.
FirstName string - The attendee's first name. Maximum length: 50 characters
HasExceptionsPrevYear Boolean - Determines whether the attendee had exceptions in the previous year, based on yearly total limits for attendees. Format: true or false
HasExceptionsYTD Boolean - Determines whether the attendee has exceptions in the current year, based on yearly total limits for attendees. Format: true or false
ID string - The unique identifier of the resource.
LastName string - The attendee's last name. Maximum length: 132 characters
MiddleInitial string - The attendee's middle initial. Maximum length: 1 character
OwnerLoginID string - The login ID of the user who owns the attendee record.
OwnerName string - The name of the user who owns the attendee record.
Suffix string - The attendee's name suffix. Maximum length: 32 characters
Title string - The attendee's title. Maximum length: 32 characters
TotalAmountPrevYear Decimal - The total amount spent on the attendee in the previous calendar year.
TotalAmountYTD Decimal - The total amount spent on the attendee in the current calendar year.
URI string - The URI to the resource.
VersionNumber Int32 - The attendee's version number.

Custom Field

Name Type Format Description
Code string - For list fields, this is the list item code.
ListItemID string - For list fields, this is the list item ID.
Type string - The custom field type. Possible values: Amount, Boolean, ConnectedList, Date, Integer, List, Number, Text
Value string - The value in the Org Unit or Custom field. For list fields, this is the name of the list item. Maximum length: 48 characters

Digital Tax Invoices

The Digital Tax Invoice web service allows digital tax invoice validators to view tax invoices and update them with a validation status. This web service currently supports the Comprobante Fiscal Digital (CFD) digital tax invoice format used in Mexico. Other countries may be supported in future releases.

Version

3.0

Retrieve All Digital Tax Invoices That Can Be Validated by the User Based On the Search Criteria

GET /api/v3.0/expense/digitaltaxinvoices

Parameters

Name Type Format Description
offset query string The starting point of the next set of results, after the limit specified in the limit field has been reached.
limit query Int32 The number of records to return. Default value: 25
modifiedafter query string A modification date for the queue record; this parameter can be used to limit the results of the GET request to the queue items that have been added since the last time the validation company queried the queue. The user must have the Web Services Admin role to use this parameter.

Request URL

https://www.concursolutions.com/api/v3.0/expense/digitaltaxinvoices?limit=5

Retrieve a Single Digital Tax Invoice by ID

GET /api/v3.0/expense/digitaltaxinvoices/{id}

Parameters

Name Type Format Description
id path string Required The ID of the digital tax invoice.

Request URL

https://www.concursolutions.com/api/v3.0/expense/digitaltaxinvoices/gWj3IHRYiHZGRTDN6y4r4LN3phszY33HT%24pQ

Update a Specified Digital Tax Invoice

PUT /api/v3.0/expense/digitaltaxinvoices/{id}

Parameters

Name Type Format Description
content body - Required A status update for the digital tax invoice.
id path string Required The ID of the digital tax invoice to update.

Schema

Digital Tax Invoices

Name Type Format Description
Items array Digital Tax Invoice The result collection.
NextPage string - The URI of the next page of results, if any.

Digital Tax Invoice

Name Type Format Description
ConcurReceiptID string - Required The ID of the digital tax invoice in plain text.
ID string - The unique identifier of the resource.
URI string - The URI to the resource.
AccountID string - Required The unique identifier assigned by the validation partner to the SAP Concur client company that owns the digital tax invoices.
DocumentID string - Required The ID of the report in plain text.
ReceiptData string - Required The digital tax invoice data.

Request URL

https://www.concursolutions.com/api/v3.0/expense/digitaltaxinvoices/gWj3IHRYiHZGUtIO83ILhbNHqCsjMmkvj%24pQ

Currency Admin Configuration

Important: This API is currently in pre-release status and is only available to approved early access participants. The API is under development and might change before being generally released. To become an early access participant, contact your SAP Concur Representative.

Currency Admin Configuration

In order for users to submit expense reports based on uploaded exchange rates, the expense administrator may consider additional configurations.

As the administrator, navigate to the Currency Admin page:

Administration >> Expense >> Expense Admin >> Currency Admin >> Settings

Exchange Rate v4

The Exchange Rate Broker API provides allows users to create custom exchange rates for a company. For additional configuration information, please see the Currency Admin Configuration page.

Limitations: The API currently allows a maximum of 100 exchange rates per POST request. This API is only available to users who have been granted access by SAP Concur. Access to this documentation does not provide access to the API.

Process Flow

Exchange Rate Broker v4 POST flow

Products and Editions

Scope Usage

Name Description Endpoint
expense.exchangerate.writeonly Create custom exchange rates. POST

Dependencies

None.

Access Token Usage

This API supports company level access tokens.

Create Custom Exchange Rates

Create a set of custom exchange rates for the given of dates and currency pairs.

Scopes

expense.exchangerate.writeonly - Refer to Scope Usage for full details.

Request

URI

Template
POST {datacenter}/exchangerate/v4/rates
Parameters

None.

Headers

Payload

Example JSON request body:

{
  "currency_sets": [
    {
      "from_crn_code": "USD",
      "start_date": "2019-01-01",
      "rate": 1.2,
      "to_crn_code": "EUR"
    }, {
      "from_crn_code": "USD",
      "start_date": "2019-01-01",
      "rate": 1.3,
      "to_crn_code": "CAD"
    }
  ]
}

Response

In case of success, the JSON response body will be the same array of exchange rate items with overallStatus, and individual rate upload statusCode and statusMessage. A bulk upload can be partially successful.

Status Codes

Headers

Payload

Successfully Created Response:

{
    "overallStatus": "Success",
    "message": "Requests completed successfully",
    "currencySets": [
        {
            "from_crn_code": "USD",
            "start_date": "2019-01-01",
            "rate": 1.2,
            "to_crn_code": "EUR",
            "statusMessage": "success",
            "statusCode": 200
        },
        {
            "from_crn_code": "USD",
            "start_date": "2019-01-01",
            "rate": 1.3,
            "to_crn_code": "CAD",
            "statusMessage": "success",
            "statusCode": 200
        }
    ]
}

Example - Success

Request

POST https://us.api.concursolutions.com/exchangerate/v4/rates
Accept: application/json
Authorization: Bearer {TOKEN}
Content-Type: application/json
{
  "currency_sets": [
    {
      "from_crn_code": "USD",
      "start_date": "2019-01-01",
      "rate": 1.2,
      "to_crn_code": "EUR"
    }
    , {
      "from_crn_code": "USD",
      "start_date": "2019-01-01",
      "rate": 1.3,
      "to_crn_code": "CAD"
    }
  ]
}

Response

HTTP/1.1 200 OK
Content-Type: application/json
Date: Thu, 01 Jan 2020 18:50:00 GMT
concur-correlationid: abcd1234-wxyz-6789-abcd-abc123456789
{
    "overallStatus": "Success",
    "message": "Requests completed successfully",
    "currencySets": [
        {
            "from_crn_code": "USD",
            "start_date": "2019-01-01",
            "rate": 1.2,
            "to_crn_code": "EUR",
            "statusMessage": "success",
            "statusCode": 200
        },
        {
            "from_crn_code": "USD",
            "start_date": "2019-01-01",
            "rate": 1.3,
            "to_crn_code": "CAD",
            "statusMessage": "success",
            "statusCode": 200
        }
    ]
}

Example - Partial Success

This example only partially succeeds to create all exchange rates due to an invalid from_crn_code in the first array entry. However, the second array entry is successfully created.

Request

POST https://us.api.concursolutions.com/exchangerate/v4/rates
Accept: application/json
Authorization: Bearer {TOKEN}
Content-Type: application/json
{
  "currency_sets": [
    {
      "from_crn_code": "INVALID",
      "start_date": "2019-01-01",
      "rate": 1.2,
      "to_crn_code": "EUR"
    }, {
      "from_crn_code": "USD",
      "start_date": "2019-01-01",
      "rate": 1.3,
      "to_crn_code": "CAD"
    }
  ]
}

Response

HTTP/1.1 200 OK
Content-Type: application/json
Date: Thu, 01 Jan 2020 18:50:00 GMT
concur-correlationid: abcd1234-wxyz-6789-abcd-abc123456789
{
    "overallStatus": "Partial Success",
    "message": "Requests completed with errors",
    "currencySets": [
        {
            "from_crn_code": "INVALID",
            "start_date": "2019-01-01",
            "rate": 1.2,
            "to_crn_code": "EUR",
            "statusMessage": "Invalid request received",
            "statusCode": 400
        },
        {
            "from_crn_code": "USD",
            "start_date": "2019-01-01",
            "rate": 1.3,
            "to_crn_code": "CAD",
            "statusMessage": "success",
            "statusCode": 200
        }
    ]
}

Schema

BulkExchangeRateUploadRequest

Name Type Format Description
currency_sets array ExchangeRateUploadRequest Required An array of exchange rate upload requests.

ExchangeRateUploadRequest

Name Type Format Description
from_crn_code string - Required ISO 4217 Alphabetic code of the currency converting from.
to_crn_code string - Required ISO 4217 Alphabetic code of the currency converting to.
start_date string YYYY-MM-DD Required UTC time for exchange rate come to be effective.
rate number - Required Custom exchange rate.

BulkExchangeRateUploadResponse

Name Type Format Description
overallStatus string - Overall status for this bulk upload.
message string - Overall message for this bulk upload.
currencySets array ExchangeRateUploadResponse Array of individual upload results.

ExchangeRateUploadResponse

Name Type Format Description
from_crn_code string - ISO 4217 alphabetic code of the currency converting from.
to_crn_code string - ISO 4217 alphabetic code of the currency converting to.
start_date string YYYY-MM-DD UTC time for exchange rate come to be effective.
rate number - Custom exchange rate.
statusCode number - HTTP status code for uploading this custom currency set.
statusMessage string - HTTP message for uploading this custom currency set.

Error

Name Type Format Description
errorId string - The unique identifier of the error associated with the response or is it error response itself.
errorMessage string - The detailed error message.
httpStatus string - The HTTP response code and phrase for the response.
path string - The URI of the attempted request.
timestamp string($date-time) - The datetime when the error was captured. Example: 2016-10-04T00:53:25.931+0000
validationErrors array ValidationError Validation errors for this request.

ValidationError

Name Type Format Description
message string - The detailed message of the validation error.
source string - The type of validation which failed.

Company Card Transactions

The corporate or credit card charges that are available for use in expense reports for the OAuth consumer.

Retrieves a list of unassigned company card charges for the user specified in the OAuth access token.

Version

1.1

URI

https://www.concursolutions.com/api/expense/expensereport/v1.1/CardCharges

Operations

GET

Request

Request Parameters

None.

Content Types

application/xml

Authorization Header

Authorization header with OAuth token for valid SAP Concur user. Required.

Response

Content Types

application/xml

Schema

This request will return a CardCharges parent element with a CardCharge child element for each transaction.

CardCharge Child Elements

Element Description
CardNumber The number of the card, with all digits obscured OTHER than last 4 digits.
ExpKey The code for the expense type of the transaction
Merchant The merchant name for the transaction.
ExpName The name of the expense type of the transaction.
TransactionAmount The amount of the card transaction.
TransactionCrnCode The currency code of the transaction amount.
TransactionDate The date of the transaction.

Examples

XML Example Request

GET https://www.concursolutions.com/api/expense/expensereport/v1.1/CardCharges/ HTTP/1.1
Authorization: OAuth {access token}
...

XML Example of Successful Response

HTTP/1.1 200 OK
Content-Type: application/xml

<CardCharges
    xmlns="https://www.concursolutions.com/api/expense/expensereport/2011/03">
    <CardCharge>
        <CardNumber>XXXXXXXXX1111</CardNumber>
        <ExpKey>CARRT</ExpKey>
        <ExpName>Car Rental</ExpName>
        <Merchant>Hertz</Merchant>
        <TransactionAmount>283.88000000</TransactionAmount>
        <TransactionCrnCode>USD</TransactionCrnCode>
        <TransactionDate>2010-08-19T00:00:00</TransactionDate>
    </CardCharge>
    <CardCharge>
        <CardNumber>XXXXXXXXX1111</CardNumber>
        <ExpKey>UNDEF</ExpKey>
        <ExpName>Undefined</ExpName>
        <Merchant>King Tires</Merchant>
        <TransactionAmount>274.13000000</TransactionAmount>
        <TransactionCrnCode>USD</TransactionCrnCode>
        <TransactionDate>2010-08-19T00:00:00</TransactionDate>
    </CardCharge>
</CardCharges>

Expense Delegators

Users that have granted delegate permissions to the another Expense user.

Retrieves the list of users that have granted delegate permissions to the user specified in the OAuth access token.

Version

1.1

URI

https://www.concursolutions.com/api/expense/expensereport/v1.1/Delegators

Operations

GET

Request

Request Parameters

None.

Headers

Authorization Header

Authorization header with OAuth token for valid SAP Concur user. Required.

Accept Header

application/xml

Response

Content Types

application/xml

Schema

This request will return a DelegatorsList parent element with a Delegator parent element for each user that has granted delegate rights to the OAuth consumer.

Delegator Elements

Element Description
CanApprove Whether the delegate is granted the right to approve expense reports on behalf of the delegator.
CanPrepare Whether the delegate is granted the right to create expense reports on behalf of the delegator.
CanSubmit Whether the delegate is granted the right to submit expense reports on behalf of the delegator.
CanTemporaryApprove Whether the delegate is granted the same temporary approval rights as the delegator.
CanViewReceipts Whether the delegate is granted the right to view receipts on behalf of the delegator.
ReceiveApprovalEmails Whether the delegate also receives the approval emails sent to the delegator.
ReceivesEmails Whether the delegate also receives the SAP Concur emails sent to the delegator.
DelegatorXUserID The user ID of the delegator.

Examples

XML Example Request

GET https://www.concursolutions.com/api/expense/expensereport/v1.1/Delegators HTTP/1.1
Authorization: OAuth {access token}
...

XML Example of Successful Response

HTTP/1.1 200 OK
Content-Type: application/xml

<DelegatorsList xmlns="http://www.concursolutions.com/api/expense/expensereport/2011/03" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
    <Delegator>
        <CanApprove>N</CanApprove>
        <CanPrepare>Y</CanPrepare>
        <CanSubmit>Y</CanSubmit>
        <CanTemporaryApprove>N</CanTemporaryApprove>
        <CanViewReceipts>Y</CanViewReceipts>
        <ReceiveApprovalEmails>N</ReceiveApprovalEmails>
        <ReceivesEmails>N</ReceivesEmails>
        <DelegatorXUserID>terryb@example.com</DelegatorXUserID>
    </Delegator>
    <Delegator>
        <CanApprove>N</CanApprove>
        <CanPrepare>Y</CanPrepare>
        <CanSubmit>Y</CanSubmit>
        <CanTemporaryApprove>N</CanTemporaryApprove>
        <CanViewReceipts>N</CanViewReceipts>
        <ReceiveApprovalEmails>N</ReceiveApprovalEmails>
        <ReceivesEmails>N</ReceivesEmails>
        <DelegatorXUserID>patd@example.com</DelegatorXUserID>
    </Delegator>
</DelegatorsList>

Entries

The Expense Entries API is used to manage expense reports and their entries in SAP Concur solutions. It allows for the synchronizing and reconciliation of expense related information with your internal systems and reporting modules.

1.1 documentation is available here.

Retrieve All Expense Entries

Version 2.0, covers a wider range of partner scenarios and is recommended as the first step. However, depending on the entries you need to retrieve, using a combination of version 2.0 and version 3.0 should be considered. To see examples, review the VAT Reclaim integration guide.

Create a New Expense Entry

POST /api/v3.0/expense/entries

Parameters

Name Type Format Description
content body - Required The expense entry object to create.
user string query The login ID of the user who owns the entries.

Request URL

https://www.concursolutions.com/api/v3.0/expense/entries

JSON Example of a Successful Response

{
  "ID": "gWidFO7ikXV647DRpQmvCXeFNA4VPTOczCg",
  "URI": "https://www.concursolutions.com/api/v3.0/expense/entries/gWidFO7ikXV647DRpQmvCXeFNA4VPTOczCg"
}

Updates an Expense Entry

PUT /api/v3.0/expense/entries/{id}

Parameters

Name Type Format Description
id string path Required The expense entry ID.
content body - Required The partial or complete expense entry object to update.

Request URL

https://www.concursolutions.com/api/v3.0/expense/entries/gWidFO7ikXV66iSvqtG6Yd0wZ%24s4ftzvzTCg

Delete an Expense Entry

DELETE /api/v3.0/expense/entries/{id}

Parameters

Name Type Format Description
id string path Required The ID of the expense entry to delete.
user string query The login ID of the user who owns the entries.

Request URL

https://www.concursolutions.com/api/v3.0/expense/entries/gWidFO7ikXV66iSvqtG6Yd0wZ%24s4ftzvzTCg

Schema

Entries

Name Type Format Description
Items array Entry The result collection.
NextPage string - The URI of the next page of results, if any.

Entry

Name Type Format Description
AllocationType string - The type of allocations for the expense. Supported values: P - partial allocation, F - full allocation, N - no allocation. Use the GET /expense/allocations function to get information about this entry's allocations.
ApprovedAmount decimal - The approved amount of the expense entry, in the report currency.
CompanyCardTransactionID string - The unique identifier for a company card transaction that is associated with this expense. Concur Expense uses the Credit Card Import job to import company card transactions. Use the GET CompanyCardTransactions function to get information about these card transactions. This element is null when there is no company card transaction associated with this expense.
Custom1 through Custom40 customField - The details from the Custom fields. These fields may not have data, depending on the configuration.
Comment string - A comment that describes the expense entry. Maximum length: 500 characters
Description string - The description of the expense. Maximum length: 64 characters
ElectronicReceiptID string - The unique identifier for an eReceipt that is associated with this expense. Use the GET eReceipts function to get information about this eReceipt. This element is null when there is no eReceipt associated with this expense.
EmployeeBankAccountID string - The unique identifier of an employee bank account that is associated with this expense. Typically, this element is used when Expense Pay reimburses the employee for this expense. Use the GET BankAccounts function to get information about this bank account.
ExchangeRate decimal - The currency conversion rate that converts the transaction amount that is in the transaction currency into the posted amount that is in the report currency. This element is typically not provided. If this element is empty for transactions in a currency different than the user's reimbursement currency, Expense will use the company's configured exchange rates to determine the posted amount for the transaction. If the system is not able to determine the exchange rate, a value of 1.0 will be used.
ExpenseTypeCode string - Required The code for the expense type. Use GET /expense/expensegroupconfigurations to learn the expense type code for expense types that are active for this report's policy.
ExpenseTypeName string - The name of the expense type, localized to the user's language.
FormID string - The ID of the form used by this expense entry.
HasAppliedCashAdvance boolean true / false Whether the entry has a cash advance applied to it.
HasAttendees boolean true / false Indicates whether the expense has attendees. Use the GET /expense/entryattendeeassociations function to get information about this entry's attendees.
HasComments boolean true / false Whether or not the expense entry has comments.
HasExceptions boolean true / false Whether the expense has exceptions. Use the GET ExpenseEntryExceptions function to get information about this entry's exceptions.
HasImage boolean true / false Indicates whether there is an entry image attached to the entry. Use the GET Entry Images function to get this entry image.
HasItemizations boolean true / false Indicates whether the expense has itemizations. Use the GET /expense/itemizations function to get information about this entry's itemizations.
HasVAT boolean true / false Indicates whether the entry has VAT data.
ID string - The unique identifier of the resource.
IsBillable boolean true / false Indicates whether the expense is billable.
IsImageRequired boolean true / false Indicates whether an entry image is required for the entry.
IsPaidByExpensePay boolean true / false Whether the entry is paid using the Expense Pay service. This element has a value if the report has reached the Processing Payment workflow step, because this is when Concur Expense determines whether it will be paid by Expense Pay.
IsPersonal boolean true / false Indicates whether the expense is personal (that is, non-reimbursable).
IsPersonalCardCharge boolean true / false Indicates whether the expense entry was imported from a personal card feed. Concur Expense uses the Yodlee API to import these card transactions.
Journey journey - Journey data. This element is used when the entry is a mileage expense. For expense types with an expense code that is either Company Car or Personal Car, the Journey child element is required. This element should not be used for expense types with an expense code that is neither Company Car nor Personal Car.
LastModified dateTime - The UTC date when the entry was last modified.
LocationCountry string - The 2-letter ISO 3166-1 country code where the expense was incurred.
LocationID string - The unique identifier for the location where the expense was incurred. Use the GET /common/locations function to get information for this location.
LocationName string - The location where the expense was incurred, usually the city name.
LocationSubdivision string - The ISO 3166-2:2007 country subdivision state, province, or other country subdivision where the expense was incurred.
OrgUnit1 through OrgUnit6 customField - The details from the Org Unit fields. These fields may not have data, depending on the configuration.
PaymentTypeID string - Required The ID of the payment type for the entry. Use GET /expense/expensegroupconfigurations to learn the payment type ID for payment types that are active for this report's expense group. For mileage expenses, use the Cash payment type. For expense types with an expense code that uses a transaction amount instead of a distance, this element is required. This element should not be used for expense types with an expense code for Company Car or Personal Car, because these two expense codes always use the Cash payment type.
PaymentTypeName string - The name of the payment type, localized to the user's language.
PostedAmount decimal - The amount of the expense entry, in the report currency.
ReceiptReceived boolean true / false Indicates whether this entry has been reviewed by a processor. Format: true or false
ReportID string - Required The report ID of the report where the entry will be added.
ReportOwnerID string - The login ID of the report owner. Use the GET User Information function to learn details about this user.
SpendCategoryCode string - The ID of the spending category that is specified for this expense entry.
SpendCategoryName string - The name of the spending category that is specified for this expense entry, localized to the user's language.
TaxReceiptType string - The receipt type for this entry. Supported values: T - tax receipt, R - regular receipt, N - no receipt
TransactionAmount decimal - Required The amount of the expense entry, in the transaction currency paid to the vendor.
TransactionCurrencyCode string - Required The 3-letter ISO 4217 currency code for the expense entry transaction amount. This is the currency in which the vendor was paid. For expense types with an expense code that uses a transaction amount instead of a distance, this element is required. This element should not be used for expense types with an expense code for Company Car or Personal Car, because for these two expense codes the currency is always the Report Currency.
TransactionDate dateTime YYYY-MM-DD Required The date when the good or service associated with this expense entry was provided.
TripID string - The unique identifier of a trip in the Itinerary Service that includes a travel booking associated with this expense. Use GET ItineraryDetails to get information about this trip and the travel booking. This element is null when there is no trip associated with the expense.
URI string - The URI to the resource.
VendorDescription string - The name of the vendor for the expense entry. Maximum length: 64 characters
VendorListItemID string - The unique identifier for a vendor list item. Use the GET /common/lists function to get information about this list item.
VendorListItemName string - The name of an item from a vendor list.

CustomField

Name Type Format Description
Code string - For list fields, this is the list item code.
ListItemID string - For list fields, this is the list item ID.
Type string - The custom field type. Supported values: Amount, Boolean, ConnectedList, Date, Integer, List, Number, Text
Value string - The value in the Org Unit or Custom field. For list fields, this is the name of the list item. Maximum length: 48 characters

Journey

Name Type Format Description
BusinessDistance Int32 - The portion of the journey for business use, in the report owner's unit of measure for distances. This element is required in order to post a personal car mileage expense entry, or to post a company car mileage expense when there is no PersonalDistance value. When using the Odometer elements, the sum of PersonalDistance and BusinessDistance must equal the difference between OdometerEnd and OdometerStart.
EndLocation string - Required Indicates where the journey ended. This is also known as the "To Location". Maximum length: 100 characters
NumberOfPassengers Int32 - The number of people in the vehicle during the journey. Used with Variable-Rate, Personal or Company Car.
OdometerEnd Int32 - The odometer reading at the end of the journey. The value must be greater than the OdometerStart value. This element is used with Variable-Rate and Company Car configuration types.
OdometerStart Int32 - The odometer reading at the start of the journey. This element is used with Variable-Rate and Company Car configuration types.
PersonalDistance Int32 - The portion of the journey for personal use. This element is required in order to post a company car mileage expense when there is no BusinessDistance value. When using the Odometer elements, the sum of PersonalDistance and BusinessDistance must equal the difference between OdometerEnd and OdometerStart. Used with Company Car configuration types.
StartLocation string - Required Indicates where the journey started. This is also known as the "From Location". Maximum length: 100 characters
UnitOfMeasure string - Required The unit of measure for distance and odometer values. Supported values: M - miles, K - kilometers

NOTE: Clients that have Car Configurations that include variable rates or custom mileage expense type codes are not supported. We only support Car Configurations that include Personal Car One-Rate definitions, using the default mileage expense type code (MILEG) where Google Maps is not set as mandatory.

Expense Form Field

The configured fields for the specified expense form.

Version

1.1

URI

https://www.concursolutions.com/api/expense/expensereport/v1.1/report/Form/_{FormId}_/Fields

Operations

GET

Get a List of Form Fields

Retrieves the details of the configured form fields for the specified form.

NOTE: When sending in requests using these fields, be sure to include the required fields from the form and any additional required fields specified in the request documentation.

Request

Request Parameters

Parameter Required/Optional Description
{FormId}/Fields required The unique identifier for the desired form and the Fields keyword.

Example: https://www.concursolutions.com/api/expense/expensereport/v1.1/report/Form/{FormId}/Fields

URI Source: The FormId is returned in the FormId element by the Get Form Data function.

Headers

Authorization Header

Authorization header with OAuth token for valid SAP Concur user. Required.

Accept Header

application/xml

Response

Response Schema

This request will return a FormFieldsList parent element with a FormField parent element for each configured form field.

FormField Elements

Element Description
Id The form field ID.
Label The form field label.
ControlType The type of field.
DataType The type of data accepted by the field.
MaxLength The maximum length of the field value.
Required Whether the field is required.
Cols The number of columns the field contains.
Access The access level the specified user has to the field.
Width The width of the field.
Custom Whether the field is custom.
Sequence The field order on the form.

XML Example Request

GET https://www.concursolutions.com/api/expense/expensereport/v1.1/report/Form/nAaT8$puKKO2$pEVlsXfSruLpDfZL0wVM$s7/Fields HTTP/1.1
Authorization: OAuth {access token}
...

XML Example of Successful Response

HTTP/1.1 200 OK
Content-Type: application/xml

<FormFieldsList xmlns="https://www.concursolutions.com/api/expense/expensereport/2011/03" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
    <FormField>
        <Id>Name</Id>
        <Label>ReportName</Label>
        <ControlType>edit</ControlType>
        <DataType>VARCHAR</DataType>
        <MaxLength>32</MaxLength>
        <Required>Y</Required>
        <Cols>32</Cols>
        <Access>RW</Access>
        <Width>32</Width>
        <Custom>N</Custom>
        <Sequence>1</Sequence>
    </FormField>
    <FormField>
        <Id>ReportId</Id>
        <Label>ReportID</Label>
        <ControlType>static</ControlType>
        <DataType>VARCHAR</DataType>
        <MaxLength>32</MaxLength>
        <Required>Y</Required>
        <Cols />
        <Access>RO</Access>
        <Width />
        <Custom>N</Custom>
        <Sequence>2</Sequence>
    </FormField>
    <FormField>
        <Id>PolKey</Id>
        <Label>Policy</Label>
        <ControlType>picklist</ControlType>
        <DataType>INTEGER</DataType>
        <MaxLength />
        <Required>Y</Required>
        <Cols />
        <Access>RW</Access>
        <Width />
        <Custom>N</Custom>
        <Sequence>3</Sequence>
    </FormField>
    <FormField>
        <Id>EmpName</Id>
        <Label>EmployeeName</Label>
        <ControlType>static</ControlType>
        <DataType>VARCHAR</DataType>
        <MaxLength>32</MaxLength>
        <Required>Y</Required>
        <Cols />
        <Access>HD</Access>
        <Width />
        <Custom>N</Custom>
        <Sequence>4</Sequence>
    </FormField>
    <FormField>
        <Id>UserDefinedDate</Id>
        <Label>ReportDate</Label>
        <ControlType>edit</ControlType>
        <DataType>TIMESTAMP</DataType>
        <MaxLength />
        <Required>N</Required>
        <Cols />
        <Access>RW</Access>
        <Width />
        <Custom>N</Custom>
        <Sequence>5</Sequence>
    </FormField>
    <FormField>
        <Id>Purpose</Id>
        <Label>BusinessPurpose</Label>
        <ControlType>textarea</ControlType>
        <DataType>VARCHAR</DataType>
        <MaxLength>500</MaxLength>
        <Required>Y</Required>
        <Cols>32</Cols>
        <Access>RW</Access>
        <Width>32</Width>
        <Custom>N</Custom>
        <Sequence>6</Sequence>
    </FormField>
</FormFieldsList>

Expense Form

The configured expense forms in SAP Concur. Clients can have multiple forms configured for each form type.

Version

1.1

URI

https://www.concursolutions.com/api/expense/expensereport/v1.1/report/Forms/

Operations

GET

Get Form Types

Retrieves the list of configured form types.

Request

Request Parameters

None.

Headers

Authorization Header

Authorization header with OAuth token for valid SAP Concur user. Required.

Accept Header

application/xml

Response

Get Form Types Schema

This request will return a FormTypesList parent element with a FormType parent element for each configured form.

FormType Elements
Element Description
Name The form type name.
FormCode The form type code.

Examples

XML Example Request

GET https://www.concursolutions.com/api/expense/expensereport/v1.1/report/Forms HTTP/1.1
Authorization: OAuth {access token}
...

XML Example of Successful Response

HTTP/1.1 200 OK
Content-Type: application/xml

<FormTypesList
    xmlns="http://www.concursolutions.com/api/expense/expensereport/2011/03"
    xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
    <FormType>
        <Name>Expense Entry</Name>
        <FormCode>ENTRYINFO</FormCode>
    </FormType>
    <FormType>
        <Name>Expense Report Header</Name>
        <FormCode>RPTINFO</FormCode>
    </FormType>
    <FormType>
        <Name>Expense Allocation</Name>
        <FormCode>ALLOCINFO</FormCode>
    </FormType>
    <FormType>
        <Name>Expense Attendee</Name>
        <FormCode>ATTNINFO</FormCode>
    </FormType>
    <FormType>
        <Name>Authorization Request Expense Category</Name>
        <FormCode>TRAVELREQENTRYINFO</FormCode>
    </FormType>
    <FormType>
        <Name>Authorization Request Header</Name>
        <FormCode>TRAVELREQINFO</FormCode>
    </FormType>
    <FormType>
        <Name>Expense Detail View</Name>
        <FormCode>EXPLISTDTL</FormCode>
    </FormType>
    <FormType>
        <Name>Attendee Detail View</Name>
        <FormCode>ATNLISTDTL</FormCode>
    </FormType>
    <FormType>
        <Name>Expense Car</Name>
        <FormCode>CARINFO</FormCode>
    </FormType>
</FormTypesList>

Get Form Data

Retrieves the list of configured forms for the specified form type.

Request

Request Parameters

Parameter Required/Optional Description
FormCode required The identifier for the desired form.

Example: https://www.concursolutions.com/api/expense/expensereport/v1.1/report/Forms/{FormCode}

URI Source: The FormCode is returned in the FormCode element in the Get Form Types response.

Headers

Authorization Header

Authorization header with OAuth token for valid SAP Concur user.

Accept Header

application/xml

Response

Get Form Data Schema

This request will return a FormDataList parent element with a FormData parent element for each configured form.

FormData Elements
Element Description
Name The form name.
FormId The form identifier.

Examples

XML Example Request

GET https://www.concursolutions.com/api/expense/expensereport/v1.1/report/Forms/RPTINFO HTTP/1.1
Authorization: OAuth {access token}
...

XML Example of Successful Response

HTTP/1.1 200 OK
Content-Type: application/xml

<FormDataList xmlns="http://www.concursolutions.com/api/expense/expensereport/2011/03" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
    <FormData>
        <Name>Central Reconciliation Columns</Name>
        <FormId>nAaT8$puKKOG5E4R9gCMyXVrFjo9NIbmQl</FormId>
    </FormData>
    <FormData>
        <Name>Central Reconciliation Report</Name>
        <FormId>nAaT8$puKKOGmK3xvAdnAOgJ9fxaoXjyW$s</FormId>
    </FormData>
    <FormData>
        <Name>Default Report Information</Name>
        <FormId>nAaT8$puKKO2$pEVlsXfSruLpDfZL0wVM$s7</FormId>
    </FormData>
</FormDataList>

Expense Group Configurations

Expense Group Configurations

Retrieves the list of Expense Polices, Expense Types and Payment Types for the Expense Group the user specified in the OAuth access token is assigned to. Each Expense Policy contains a list of valid Expense Types. The Payment Types are associated with the user’s Expense Group and apply to all the returned policies. Only the payment types that are valid for the Post Expense Entry endpoint are returned.

NOTE: The Concur Expense product is highly configurable, and each client may have a unique set of payment types. If a payment type is not included in the response, it is not available for use with this client.

Version

3.0

1.1 documentation is available here

Retrieve a configuration of an expense group

GET /api/v3.0/expense/expensegroupconfigurations

Parameters

Name Type Format Description
user string query The login ID of the user associated with this expense group configuration. The user must have the Web Services Admin role to use this parameter.
offset string query The starting point of the next set of results, after the limit specified in the limit field has been reached.
limit Int32 query The number of records to return Default value: 10

Request URL

https://www.concursolutions.com/api/v3.0/expense/expensegroupconfigurations?user=ALL&limit=10

JSON example of a successful response

{
  "Items": [
    {
      "Name": "United Kingdom",
      "AttendeeListFormID": "gWh2aF2cfwJElRBMIJ9ahYnTVXDIp1fQUdg",
      "AttendeeListFormName": "Default Attendee Detail View",
      "AllowUserRegisterYodlee": false,
      "AllowUserDigitalTaxInvoice": false,
      "CashAdvance": null,
      "PaymentTypes": [
        {
          "ID": "gWurF7TC$pQAT4cqT0JokiYMobzQdz",
          "Name": "Cash",
          "IsDefault": false
        },
        {
          "ID": "gWurL7jy84a4BAdqGaTNrtiABiqpM",
          "Name": "Company Paid",
          "IsDefault": false
        },
        {
          "ID": "gWvnH$pTyEPYFerdCk8rjvoSpmM4L0",
          "Name": "Pending Card Transaction",
          "IsDefault": false
        }
      ],
      "Policies": [
        {
          "ID": "gWmINGEAkRfLbo7HmBh5USB3$pS8HMWDoP2Q",
          "Name": "*Global Expense Policy",
          "IsDefault": false,
          "IsInheritable": true,
          "ExpenseTypes": [
            {
              "Code": "LODNG",
              "Name": "Hotel",
              "ExpenseCode": "LODGING"
            }
          ]
        }
      ]
    }
  ]
}

Retrieve an expense group configuration by ID

GET /api/v3.0/expense/expensegroupconfigurations/{id}

Parameters

Name Type Format Description
id string path Required The ID of the expense group configuration.
user string query The login ID of the user associated with this expense group configuration. The user must have the Web Services Admin role to use this parameter.

Schema

Expense Group Configurations

Name Type Format Description
id string path Required The ID of the expense group configuration.
user string query The login ID of the user associated with this expense group configuration. The user must have the Web Services Admin role to use this parameter.

Expense Group Configuration

Name Type Format Description
AllowUserDigitalTaxInvoice Boolean - Indicates whether users are allowed to upload digital tax invoices. Format: true or false
AllowUserRegisterYodlee Boolean - Indicates whether users in the expense group are allowed to register Yodlee credit cards. Format: true or false
AttendeeListFormID string - The unique identifier for the attendee list form.
AttendeeListFormName string - The name of the attendee list form.
AttendeeTypes array[AttendeeType] - The list of attendee types.
CashAdvance CashAdvance - The amount of the cash advance.
ID string - The unique identifier of the resource.
Name string - The name of the expense group configuration.
PaymentTypes array Payment Type The list of payment types.
Policies array Policy The list of policies and expense types.
URI string - The URI to the resource.

Attendee Type

Name Type Format Description
Code string - The attendee type code.
Name string - The name of the attendee type.

Cash Advance

Name Type Format Description
AllowUserCarryBalance Boolean - Indicates whether users are allowed to carry a cash advance balance forward from one report to another. Format: true or false
AllowUserLinkMultiple Boolean - Indicates whether users are allowed to link multiple cash advances to one expense report. Format: true or false
AllowUserUpdateExchangeRate Boolean - Indicates whether users are allowed to update the currency exchange rate for expense entries. Format: true or false
Name string - The name of the cash advance workflow.
WorkflowID string - The unique identifier for the cash advance workflow. Null means there is no such workflow.

Payment Type

Name Type Format Description
ID string - The unique identifier of the resource.
IsDefault Boolean - Determines whether this payment type is the default. Format: true or false
Name string - The name of the payment type.

Policy

Name Type Format Description
ExpenseTypes array ExpenseType The parent element for the list of expense types in the policy.
ID string - The unique identifier of the resource.
IsDefault Boolean - Indicates whether this policy is the default. Format: true or false
IsInheritable Boolean - Indicates whether the descendent nodes in the Expense Feature Hierarchy are covered by this policy. Format: true or false
Name string - The name of the policy.

Expense Type

Name Type Format Description
Code string - The code for the expense type. Expense types define expenses within an expense category. For example, Business Meal is an expense type in the MEALS category.
ExpenseCode string - The code for the expense category. The expense category code controls the function of an expense entry. Format: OTHER - Standard, COCARMILE - Company Car, PCARMILE - Personal Car, MFUEL - Fuel For Mileage, LODGING - Lodging, MEALS - Meals, OTHERNP - Other Not Partially Approvable, JPYPTRAN - Japanese Public Transportation
Name string - The name of the expense type.

Request URL

https://www.concursolutions.com/api/v3.0/expense/expensegroupconfigurations/gWv5bj%24sPY1weV9audTTRp7PkBlea3Y6aizg

JSON example of a successful response

{
  "Name": "United Kingdom",
  "AttendeeListFormID": "gWh2aF2cfwJElRBMIJ9ahYnTVXDIp1fQUdg",
  "AttendeeListFormName": "Default Attendee Detail View",
  "AllowUserRegisterYodlee": false,
  "AllowUserDigitalTaxInvoice": false,
  "CashAdvance": null,
  "PaymentTypes": [
    {
      "ID": "gWurF7TC$pQAT4cqT0JokiYMobzQdz",
      "Name": "Cash",
      "IsDefault": false
    },
    {
      "ID": "gWurL7jy84a4BAdqGaTNrtiABiqpM",
      "Name": "Company Paid",
      "IsDefault": false
    },
    {
      "ID": "gWvnH$pTyEPYFerdCk8rjvoSpmM4L0",
      "Name": "Pending Card Transaction",
      "IsDefault": false
    }
  ],
  "Policies": [
    {
      "ID": "gWmINGEAkRfLbo7HmBh5USB3$pS8HMWDoP2Q",
      "Name": "*Global Expense Policy",
      "IsDefault": false,
      "IsInheritable": true,
      "ExpenseTypes": [
        {
          "Code": "LODNG",
          "Name": "Hotel",
          "ExpenseCode": "LODGING"
        },
        {
          "Code": "LODTX",
          "Name": "Hotel Tax",
          "ExpenseCode": "LODGING"
        },
        {
          "Code": "LNDRY",
          "Name": "Laundry",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "AIRFR",
          "Name": "Airfare",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01026",
          "Name": "Airline Fees",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "CARRT",
          "Name": "Car Rental",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "CARMI",
          "Name": "Company Car Mileage",
          "ExpenseCode": "COCARMILE"
        },
        {
          "Code": "GASXX",
          "Name": "Fuel",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "PARKG",
          "Name": "Parking",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "MILEG",
          "Name": "Personal Car Mileage",
          "ExpenseCode": "PCARMILE"
        },
        {
          "Code": "TRAIN",
          "Name": "Public Transport",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "TAXIX",
          "Name": "Taxi",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "TOLLS",
          "Name": "Tolls/Road Charges",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01025",
          "Name": "Train",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "BRKFT",
          "Name": "Breakfast",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "DINNR",
          "Name": "Dinner",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01028",
          "Name": "Individual Meals",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "LUNCH",
          "Name": "Lunch",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "BUSML",
          "Name": "Entertainment - Clients",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01004",
          "Name": "Entertainment - Staff",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01005",
          "Name": "Courier/Shipping/Freight",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "OFCSP",
          "Name": "Office Equipment/Hardware",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01007",
          "Name": "Office Supplies/Software",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "POSTG",
          "Name": "Postage",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01006",
          "Name": "Printing/Photocopying/Stationery",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01035",
          "Name": "Business Calls",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "ONLIN",
          "Name": "Internet/Online Fees",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "CELPH",
          "Name": "Mobile/Cellular Phone",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01036",
          "Name": "Non-Business Calls",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "LOCPH",
          "Name": "Telephone/Fax",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "BANKF",
          "Name": "Bank Fees",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01024",
          "Name": "Currency Exchange Fees",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01011",
          "Name": "Medical Fees",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01008",
          "Name": "Passports/Visa Fees",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "AWRDS",
          "Name": "Gifts - Clients",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "GIFTS",
          "Name": "Gifts - Staff",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "TRDSH",
          "Name": "Marketing/Promotional Costs",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "MISCL",
          "Name": "Miscellaneous",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01014",
          "Name": "Newspapers/Magazines/Books",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "DUESX",
          "Name": "Professional Subscriptions/Dues",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "SEMNR",
          "Name": "Seminar/Course fees",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01009",
          "Name": "Tips/Gratuities",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01012",
          "Name": "Tuition/Training Reimbursement",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01010",
          "Name": "Ex Pat Expenses",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01017",
          "Name": "Relocation Expenses",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "CSHRN",
          "Name": "Cash Advance Return",
          "ExpenseCode": "OTHERNP"
        },
        {
          "Code": "CURGL",
          "Name": "Currency Gain/Loss",
          "ExpenseCode": "OTHERNP"
        },
        {
          "Code": "01052",
          "Name": "Fixed Vehicle Reimbursement",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01053",
          "Name": "Motus Other Amount",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01054",
          "Name": "Variable Vehicle Reimbursement",
          "ExpenseCode": "OTHER"
        }
      ]
    },
    {
      "ID": "gWmINGEAkRfGsCKjw8DAec1dbfF$pV$sxbfpw",
      "Name": "Germany Expense Policy",
      "IsDefault": null,
      "IsInheritable": null,
      "ExpenseTypes": [
        {
          "Code": "LODNG",
          "Name": "Hotel",
          "ExpenseCode": "LODGING"
        },
        {
          "Code": "LODTX",
          "Name": "Hotel Tax",
          "ExpenseCode": "LODGING"
        },
        {
          "Code": "LNDRY",
          "Name": "Laundry",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "AIRFR",
          "Name": "Airfare",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01026",
          "Name": "Airline Fees",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01002",
          "Name": "Car Maintenance/Repairs ",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "CARRT",
          "Name": "Car Rental",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "GASXX",
          "Name": "Fuel",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "PARKG",
          "Name": "Parking",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "MILEG",
          "Name": "Personal Car Mileage",
          "ExpenseCode": "PCARMILE"
        },
        {
          "Code": "TRAIN",
          "Name": "Public Transport",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "TAXIX",
          "Name": "Taxi",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "TOLLS",
          "Name": "Tolls/Road Charges",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01025",
          "Name": "Train",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "BRKFT",
          "Name": "Breakfast",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "DINNR",
          "Name": "Dinner",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "LUNCH",
          "Name": "Lunch",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01055",
          "Name": "EBR 1190",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01030",
          "Name": "Entertainment - External (Domestic)",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01031",
          "Name": "Entertainment - External (Foreign)",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01004",
          "Name": "Entertainment - Staff",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01005",
          "Name": "Courier/Shipping/Freight",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "OFCSP",
          "Name": "Office Equipment/Hardware",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01007",
          "Name": "Office Supplies/Software",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "POSTG",
          "Name": "Postage",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01006",
          "Name": "Printing/Photocopying/Stationery",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01035",
          "Name": "Business Calls",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "ONLIN",
          "Name": "Internet/Online Fees",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "CELPH",
          "Name": "Mobile/Cellular Phone",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01036",
          "Name": "Non-Business Calls",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "LOCPH",
          "Name": "Telephone/Fax",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "BANKF",
          "Name": "Bank Fees",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01024",
          "Name": "Currency Exchange Fees",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01011",
          "Name": "Medical Fees",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01008",
          "Name": "Passports/Visa Fees",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01033",
          "Name": "Gifts <= 35€",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01032",
          "Name": "Gifts > 35€",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "TRDSH",
          "Name": "Marketing/Promotional Costs",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "MISCL",
          "Name": "Miscellaneous",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01014",
          "Name": "Newspapers/Magazines/Books",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "DUESX",
          "Name": "Professional Subscriptions/Dues",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "SEMNR",
          "Name": "Seminar/Course fees",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01009",
          "Name": "Tips/Gratuities",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01012",
          "Name": "Tuition/Training Reimbursement",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01010",
          "Name": "Ex Pat Expenses",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01017",
          "Name": "Relocation Expenses",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "CSHRN",
          "Name": "Cash Advance Return",
          "ExpenseCode": "OTHERNP"
        },
        {
          "Code": "CURGL",
          "Name": "Currency Gain/Loss",
          "ExpenseCode": "OTHERNP"
        }
      ]
    },
    {
      "ID": "gWmINGEAkQoarrf1JiyI8$sqI$s00T30OfIlA",
      "Name": "Italy Expense Policy",
      "IsDefault": null,
      "IsInheritable": null,
      "ExpenseTypes": [
        {
          "Code": "LODNG",
          "Name": "Hotel",
          "ExpenseCode": "LODGING"
        },
        {
          "Code": "LODTX",
          "Name": "Hotel Tax",
          "ExpenseCode": "LODGING"
        },
        {
          "Code": "LNDRY",
          "Name": "Laundry",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "AIRFR",
          "Name": "Airfare",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01026",
          "Name": "Airline Fees",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01002",
          "Name": "Car Maintenance/Repairs ",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "CARRT",
          "Name": "Car Rental",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "GASXX",
          "Name": "Fuel",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "PARKG",
          "Name": "Parking",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "MILEG",
          "Name": "Personal Car Mileage",
          "ExpenseCode": "PCARMILE"
        },
        {
          "Code": "TRAIN",
          "Name": "Public Transport",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "TAXIX",
          "Name": "Taxi",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "TOLLS",
          "Name": "Tolls/Road Charges",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01025",
          "Name": "Train",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01043",
          "Name": "Alcoholic Beverages & Softs Drinks",
          "ExpenseCode": "MEALS"
        },
        {
          "Code": "BRKFT",
          "Name": "Breakfast",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "DINNR",
          "Name": "Dinner",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01028",
          "Name": "Individual Meals",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01044",
          "Name": "Individual Meals - Within Municipality",
          "ExpenseCode": "MEALS"
        },
        {
          "Code": "LUNCH",
          "Name": "Lunch",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "BUSML",
          "Name": "Entertainment - Clients",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01004",
          "Name": "Entertainment - Staff",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01005",
          "Name": "Courier/Shipping/Freight",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "OFCSP",
          "Name": "Office Equipment/Hardware",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "POSTG",
          "Name": "Postage",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01006",
          "Name": "Printing/Photocopying/Stationery",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01035",
          "Name": "Business Calls",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "ONLIN",
          "Name": "Internet/Online Fees",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "CELPH",
          "Name": "Mobile/Cellular Phone",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01036",
          "Name": "Non-Business Calls",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "LOCPH",
          "Name": "Telephone/Fax",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "BANKF",
          "Name": "Bank Fees",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01024",
          "Name": "Currency Exchange Fees",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01008",
          "Name": "Passports/Visa Fees",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "AWRDS",
          "Name": "Gifts - Clients",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "GIFTS",
          "Name": "Gifts - Staff",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "TRDSH",
          "Name": "Marketing/Promotional Costs",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01014",
          "Name": "Newspapers/Magazines/Books",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "DUESX",
          "Name": "Professional Subscriptions/Dues",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "SEMNR",
          "Name": "Seminar/Course fees",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01009",
          "Name": "Tips/Gratuities",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01012",
          "Name": "Tuition/Training Reimbursement",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01045",
          "Name": "Undocumented Incidentals - Domestic",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01046",
          "Name": "Undocumented Incidentals - International",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "CSHRN",
          "Name": "Cash Advance Return",
          "ExpenseCode": "OTHERNP"
        },
        {
          "Code": "CURGL",
          "Name": "Currency Gain/Loss",
          "ExpenseCode": "OTHERNP"
        }
      ]
    },
    {
      "ID": "gWmINGEAkQoapyOLKfSdm0A9qK0ZVUvwolA",
      "Name": "US Expense Policy",
      "IsDefault": null,
      "IsInheritable": null,
      "ExpenseTypes": [
        {
          "Code": "LODNG",
          "Name": "Hotel",
          "ExpenseCode": "LODGING"
        },
        {
          "Code": "LODTX",
          "Name": "Hotel Tax",
          "ExpenseCode": "LODGING"
        },
        {
          "Code": "INCTS",
          "Name": "Incidentals",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "LNDRY",
          "Name": "Laundry",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01057",
          "Name": "Test4",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "AIRFR",
          "Name": "Airfare",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01026",
          "Name": "Airline Fees",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01002",
          "Name": "Car Maintenance/Repairs ",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "CARRT",
          "Name": "Car Rental",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "CARMI",
          "Name": "Company Car Mileage",
          "ExpenseCode": "COCARMILE"
        },
        {
          "Code": "GASXX",
          "Name": "Fuel",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "PARKG",
          "Name": "Parking",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "MILEG",
          "Name": "Personal Car Mileage",
          "ExpenseCode": "PCARMILE"
        },
        {
          "Code": "TRAIN",
          "Name": "Public Transport",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "TAXIX",
          "Name": "Taxi",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "TOLLS",
          "Name": "Tolls/Road Charges",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01025",
          "Name": "Train",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "BRKFT",
          "Name": "Breakfast",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01027",
          "Name": "Business Meals (Attendees)",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "DINNR",
          "Name": "Dinner",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "LUNCH",
          "Name": "Lunch",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "BUSML",
          "Name": "Entertainment - Clients",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01004",
          "Name": "Entertainment - Staff",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01005",
          "Name": "Courier/Shipping/Freight",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "OFCSP",
          "Name": "Office Equipment/Hardware",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01007",
          "Name": "Office Supplies/Software",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "POSTG",
          "Name": "Postage",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01006",
          "Name": "Printing/Photocopying/Stationery",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01035",
          "Name": "Business Calls",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "ONLIN",
          "Name": "Internet/Online Fees",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "CELPH",
          "Name": "Mobile/Cellular Phone",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01036",
          "Name": "Non-Business Calls",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "LOCPH",
          "Name": "Telephone/Fax",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01047",
          "Name": "Agency Booking Fees",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "BANKF",
          "Name": "Bank Fees",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01024",
          "Name": "Currency Exchange Fees",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01008",
          "Name": "Passports/Visa Fees",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "AWRDS",
          "Name": "Gifts - Clients",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "GIFTS",
          "Name": "Gifts - Staff",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "TRDSH",
          "Name": "Marketing/Promotional Costs",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "MISCL",
          "Name": "Miscellaneous",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01014",
          "Name": "Newspapers/Magazines/Books",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "DUESX",
          "Name": "Professional Subscriptions/Dues",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "SEMNR",
          "Name": "Seminar/Course fees",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01038",
          "Name": "Staff Awards/Incentives",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01009",
          "Name": "Tips/Gratuities",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01012",
          "Name": "Tuition/Training Reimbursement",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "CSHRN",
          "Name": "Cash Advance Return",
          "ExpenseCode": "OTHERNP"
        },
        {
          "Code": "CURGL",
          "Name": "Currency Gain/Loss",
          "ExpenseCode": "OTHERNP"
        },
        {
          "Code": "01052",
          "Name": "Fixed Vehicle Reimbursement",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01053",
          "Name": "Motus Other Amount",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01054",
          "Name": "Variable Vehicle Reimbursement",
          "ExpenseCode": "OTHER"
        }
      ]
    }
  ],
  "AttendeeTypes": [
    {
      "Code": "PRIVATE",
      "Name": "Attendee-Private List"
    },
    {
      "Code": "HCOCGDM",
      "Name": "Cegedim HCO Search–OneKey US"
    }
  ],
  "ID": "gWv5bj$sPY1weV9audTTRp7PkBlea3Y6aizg",
  "URI": "https://www.concursolutions.com/api/v3.0/expense/expensegroupconfigurations/gWv5bj$sPY1weV9audTTRp7PkBlea3Y6aizg"
}

Itemizations

Itemizations

Version

3.0 Note that some methods are deprecated

1.1 documentation is available here

Retrieve all expense itemizations owned by the user

DEPRECATED: 05/19/2016 UNSUPPORTED: 11/19/2016

GET /api/v3.0/expense/itemizations

Parameters

Name Type Format Description
reportID string query The report ID of the itemizations to be retrieved. Use the GET /expense/reportdigests function to find the report ID. Format: An alpha-numeric string
entryID string query The entry ID for the itemizations to be retrieved. Use the GET /expense/entries endpoint to learn the valid entry ID.
expenseTypeCode string query The expense type code for the itemizations to be retrieved.
offset string query The starting point of the next set of results, after the limit specified in the limit field has been reached.
limit Int32 query The number of records to return. Default value: 25
user string query The login ID of the user who owns the itemizations. The user must have the Web Services Admin role to use this parameter.

Request URL

https://www.concursolutions.com/api/v3.0/expense/itemizations?limit=10&user=ALL

JSON example of a successful response

{
  "Items": [
    {
      "EntryID": "gWidFO7ikXSy55WZOaAXv8JRfFkruCwrP4g",
      "ReportID": "F4F027007E814C1CA70E",
      "ReportOwnerID": "CAtraveler@concurconnect2.com",
      "ExpenseTypeCode": "LODTX",
      "ExpenseTypeName": "Hotel Tax",
      "SpendCategoryCode": "LODGA",
      "SpendCategoryName": "Lodging - Track Room Rate Spending",
      "TransactionDate": "2013-08-07T00:00:00",
      "TransactionAmount": 20,
      "PostedAmount": 20,
      "ApprovedAmount": 20,
      "LocationID": "gWqWg2EhaUtcIW$s2pMbTGM8W81u2qcfX94w",
      "LocationName": "Montreal, Quebec",
      "LocationSubdivision": "Quebec",
      "LocationCountry": "CA",
      "Description": "test",
      "IsPersonal": false,
      "IsBillable": false,
      "IsImageRequired": false,
      "AllocationType": "N",
      "HasComments": false,
      "HasExceptions": false,
      "LastModified": "2013-09-02T19:40:48.877",
      "OrgUnit1": null,
      "OrgUnit2": null,
      "OrgUnit3": null,
      "OrgUnit4": null,
      "OrgUnit5": null,
      "OrgUnit6": null,
      "Custom1": null,
      "Custom2": null,
      "Custom3": null,
      "Custom4": null,
      "Custom5": null,
      "Custom6": null,
      "Custom7": null,
      "Custom8": null,
      "Custom9": null,
      "Custom10": null,
      "Custom11": null,
      "Custom12": null,
      "Custom13": null,
      "Custom14": null,
      "Custom15": null,
      "Custom16": null,
      "Custom17": null,
      "Custom18": null,
      "Custom19": null,
      "Custom20": null,
      "Custom21": null,
      "Custom22": null,
      "Custom23": null,
      "Custom24": null,
      "Custom25": null,
      "Custom26": null,
      "Custom27": null,
      "Custom28": null,
      "Custom29": null,
      "Custom30": null,
      "Custom31": null,
      "Custom32": null,
      "Custom33": null,
      "Custom34": null,
      "Custom35": null,
      "Custom36": null,
      "Custom37": null,
      "Custom38": null,
      "Custom39": null,
      "Custom40": null,
      "ID": "gWidFO7ikXSy$seMkLiQismjUIYkxYzCsf4g",
      "URI": "https://www.concursolutions.com/api/v3.0/expense/itemizations/gWidFO7ikXSy$seMkLiQismjUIYkxYzCsf4g"
    }
  ]
}

Retrieve an expense itemization by ID

GET /api/v3.0/expense/itemizations/{id}

Parameters

Name Type Format Description
id string path Required The ID of the expense itemization.
user string query The login ID of the user who owns the itemizations. The user must have the Web Services Admin role to use this parameter.

Request URL

https://www.concursolutions.com/api/v3.0/expense/itemizations/gWidFO7ikXV6%24pcZsso2aBN0Aad4P5i8bjCg

JSON example of a successful response

{
  "EntryID": "gWidFO7ikXV6$sQxTtWGQsIhawC4KoyssTCg",
  "ReportID": "39BD9F7C5C3F4986A6A5",
  "ReportOwnerID": "jimadmin@concurconnect2.com",
  "ExpenseTypeCode": "LODTX",
  "ExpenseTypeName": "Hotel Tax",
  "SpendCategoryCode": "LODGA",
  "SpendCategoryName": "Lodging - Track Room Rate Spending",
  "TransactionDate": "2016-04-21T00:00:00",
  "TransactionAmount": 20,
  "PostedAmount": 20,
  "ApprovedAmount": 20,
  "LocationID": "gWqWg2EhcUKB$sottpx8eODvjn1$pWvWfG15A",
  "LocationName": "Bellevue, Washington",
  "LocationSubdivision": "Washington",
  "LocationCountry": "US",
  "Description": null,
  "IsPersonal": false,
  "IsBillable": false,
  "IsImageRequired": false,
  "AllocationType": "N",
  "HasComments": false,
  "HasExceptions": false,
  "LastModified": "2016-04-22T22:19:55.213",
  "OrgUnit1": null,
  "OrgUnit2": null,
  "OrgUnit3": null,
  "OrgUnit4": null,
  "OrgUnit5": null,
  "OrgUnit6": null,
  "Custom1": null,
  "Custom2": null,
  "Custom3": null,
  "Custom4": null,
  "Custom5": null,
  "Custom6": null,
  "Custom7": null,
  "Custom8": null,
  "Custom9": null,
  "Custom10": null,
  "Custom11": null,
  "Custom12": null,
  "Custom13": null,
  "Custom14": null,
  "Custom15": null,
  "Custom16": null,
  "Custom17": null,
  "Custom18": null,
  "Custom19": null,
  "Custom20": null,
  "Custom21": null,
  "Custom22": null,
  "Custom23": null,
  "Custom24": null,
  "Custom25": null,
  "Custom26": null,
  "Custom27": null,
  "Custom28": null,
  "Custom29": null,
  "Custom30": null,
  "Custom31": null,
  "Custom32": null,
  "Custom33": null,
  "Custom34": null,
  "Custom35": null,
  "Custom36": null,
  "Custom37": null,
  "Custom38": null,
  "Custom39": null,
  "Custom40": null,
  "ID": "gWidFO7ikXV6$pcZsso2aBN0Aad4P5i8bjCg",
  "URI": "https://www.concursolutions.com/api/v3.0/expense/itemizations/gWidFO7ikXV6$pcZsso2aBN0Aad4P5i8bjCg"
}

Create a new expense itemization

POST /api/v3.0/expense/itemizations

Parameters

Name Type Format Description
content - body Required The expense itemization object to create.

Request URL

https://www.concursolutions.com/api/v3.0/expense/itemizations

JSON example of a successful response

{
  "ID": "gWidFO7ikXV69FISvVWPbHe1Oj4FbCd0DCg",
  "URI": "https://www.concursolutions.com/api/v3.0/expense/itemizations/gWidFO7ikXV69FISvVWPbHe1Oj4FbCd0DCg"
}

Update an expense itemization

DEPRECATED: 05/19/2016 UNSUPPORTED: 11/19/2016

PUT /api/v3.0/expense/itemizations/{id}

Parameters

Name Type Format Description
id string path Required The ID of the expense itemization
content - body Required The partial or complete expense itemization object to update.

Request URL

https://www.concursolutions.com/api/v3.0/expense/itemizations/gWidFO7ikXV6%24pcZsso2aBN0Aad4P5i8bjCg

JSON example of a successful response

no content

Delete an expense itemization

DEPRECATED: 05/19/2016 UNSUPPORTED: 11/19/2016

DELETE /api/v3.0/expense/itemizations/{id}

Parameters

Name Type Format Description
id string path Required The ID of the expense itemization to delete.
user string query Required The login ID of the user who owns the itemizations. The user must have the Web Services Admin role to use this parameter.

Request URL

https://www.concursolutions.com/api/v3.0/expense/itemizations/gWidFO7ikXV6%24pcZsso2aBN0Aad4P5i8bjCg

JSON example of a successful response

no content

Schema

Itemizations

Name Type Format Description
Items array Itemization The result collection.
NextPage string - The URI of the next page of results, if any.

Itemization

Name Type Format Description
AllocationType string - The type of allocation for the itemization. Possible values: P - partial allocation, F - full allocation, N - no allocation. Use the GET /expense/allocations function to get information about this entry's allocations.
ApprovedAmount Decimal - The approved amount of the expense itemization, in the report currency.
Custom1 through Custom40 CustomField - The details from the Custom fields. These fields may not have data, depending on the configuration. If the form field is configured as a List data type, the value will be the item code for this list. Use the GET /common/listitems operation to learn the item name. Maximum length: 64 characters
Description string - The description of the expense. Maximum length: 64 characters
EntryID string - Required The ID of the expense entry that is the parent for the itemization. Use the GET /expense/entries endpoint to learn the entry ID for the expense itemizations.
ExpenseTypeCode string - Required The code for the expense type. Use the GET /expense/expensegroupconfigurations endpoint to learn the expense type code for expense types that are active for this report's policy.
ExpenseTypeName string - Required The name of the expense type, localized to the user's language.
HasComments Boolean - Indicates whether the expense has comments. Use the GET ExpenseEntryComments endpoint to get information about this entry's comments. Format: true or false
HasExceptions Boolean - Indicates whether the expense has exceptions. Format: true or false
ID string - The unique identifier of the resource.
IsBillable Boolean - Indicates whether the itemization is billable. Format: true or false
IsImageRequired Boolean - Indicates whether a receipt image is required for the entry. Format: true or false
IsPersonal Boolean - Indicates whether the itemization is personal (that is, non-reimbursable). Format: true or false
LastModified DateTime - The UTC date when the itemization was last modified.
LocationCountry string - The country where the expense was incurred. Format: 2-letter ISO 3166-1 country code
LocationID string - The unique identifier for the location where the expense was incurred. Use the GET /common/locations function to get information for this location.
LocationName string - The location where the expense was incurred, usually the city name.
LocationSubdivision string - The state, province, or other country subdivision where the expense was incurred. Format: ISO 3166-2:2007 country subdivision
OrgUnit1 through OrgUnit6 CustomField - The details from the Org Unit fields. These fields may not have data, depending on the configuration. If the form field is configured as a List data type, the value will be the item code for this list. Use the GET /common/listitems operation to learn the item name. Maximum length: 64 characters
PostedAmount Decimal - The amount of the expense itemization, in the report currency.
ReportID string - Required The ID of the report that is the parent for the itemization. Use the GET /expense/reportdigests endpoint to learn the report ID for the itemizations.
ReportOwnerID string - Required The login ID for the report owner. Use the GET User Information endpoint to learn details about this user.
SpendCategoryCode string - Required The code for the spending category that is specified for this itemization.
SpendCategoryName string - Required The name of the spending category that is specified for this itemization, localized to the user's language.
TransactionAmount Decimal - The amount of the expense itemization, in the transaction currency of the parent expense entry.
TransactionDate DateTime - Required The date when the good or service associated with this itemization was provided. Format: YYYY-MM-DD
URI string - The URI to the resource.

Custom Field

Name Type Format Description
Code string - For list fields, this is the list item code.
ListItemID string - For list fields, this is the list item ID.
Type string - The custom field type. Possible values: Amount, Boolean, ConnectedList, Date, Integer, List, Number, Text
Value string - The value in the Org Unit or Custom field. For list fields, this is the name of the list item. Maximum length: 48 characters

Get report details

Retrieves the full set of information for the report. Includes the Report Header, Entry, Attendee, Itemization and Allocation details.

Some elements will appear only if the OAuth consumer has the Web Services Admin role. These include: The ReportKey element, the employee's credit card information, and the employee's bank account information, VAT information, Journal entries. Connectors that utilize this information go through a review process with SAP Concur that includes verification of secure data handling.

GET list of reports can be found here

Request

Request Parameters

Path Parameters

Parameter Required/Optional Description
reportId required The identifier for the desired report.

Example: https://us.api.concursolutions.com/api/expense/expensereport/v2.0/report/{reportId}

URI Source: The ReportId is returned in the ReportId element of the Get List of Reports function

Headers

Authorization Header

Authorization header with OAuth token for valid SAP Concur user. The OAuth consumer must have one of the following user roles in SAP Concur: Company Administrator or Web Services Administrator for Professional, or Can Administer for Standard. These roles allow the user to manage data for the entire company.

Accept Header

application/xml

Response

Content Types

application/xml

Schema

This request will return a ReportDetails parent element.

ReportDetails

Element Description
UserLoginID The user ID of the report owner. Maximum 128 characters.
EmployeeName The name of the employee who created the report. Maximum 66 characters.
ReportID The unique identifier for the report, which appears in the Concur Expense UI. Maximum 32 character varchar.
ReportKey The unencrypted unique identifier for the report, that appears on the report header. The element appears only if the OAuth consumer has the Web Services Admin role in SAP Concur. Maximum 48 characters.
ReportName The name of the report. Maximum 40 characters.
Purpose The information from the Business Purpose field.
ReportDate The date from the report header. Format: YYYY-MM-DDThh:mm:ss
CreationDate The date the report was created. Format: YYYY-MM-DDThh:mm:ss
SubmitDate The date the report was submitted. Maximum 10 characters.
PaidDate The date the report was extracted for payment. This element has an attribute named i:nil. If the value for this element is null, the i:nil attribute will be set to true. Format: YYYY-MM-DDThh:mm:ss
CurrencyCode The 3-letter ISO 4217 currency code for the expense report currency. The expense report currency is defined as the report creator's default reimbursement currency.
ReportTotal The total amount of the report. Maximum 23 characters.
PersonalExpenses The total amount of expenses marked as personal. Maximum 23 characters.
AmountDueEmployee The total amount due to the employee for the report. Maximum 23 characters.
AmountDueCompanyCard The total amount due to the company card for the report. Maximum 23 characters.
TotalClaimedAmount The total amount of all non-personal expenses in the report. Maximum 23 characters.
TotalApprovedAmount The total amount of approved expenses in the report. Maximum 23 characters.
ApprovalStatusCode The approval status code for the report.
ApprovalStatusName The approval status name for the report.
PaymentStatusCode The unique identifier for the payment status of the report.
PaymentStatusName The payment status of the report.
OrgUnit1 through OrgUnit6 The details from the Org Unit custom fields. These may not have data, depending on configuration. Maximum 48 characters for each field.
Custom1 through Custom20 The details from the Custom fields. These may not have data, depending on configuration. If report owner information is stored in these fields, it may be outdated. Refer to the ReportOwner parent element for the current owner information. Refer to the Custom Fields Child Elements table for more information.
LedgerName The name of the expense report ledger. Maximum 20 characters.
PolicyID The unique identifier of the policy that applies to this report. Maximum 64 characters.
EverSentBack Whether the report has ever been sent back to the employee. Format: Y/N
HasException Whether the report has exceptions. Format: Y/N
WorkflowActionURL The URL to post a workflow action to the report using the Post Report Workflow Action function.
ExpenseEntriesList This parent element has an ExpenseEntry child element for each entry. Refer to the ExpenseEntry elements table for more information.
ReportImageURL The URL to access the image associated with the report. This URL is valid for 30 minutes after the web service call.
Country The report country. Maximum 2 characters. Format: The ISO 3166-1 alpha-2 country code. Example: United States is US.
CountrySubdivision The report country subdivision. Format: ISO 3166-2:2007 country subdivision.
ProcessingPaymentDate The date that the report completed all approvals and was ready to be extracted for payment. Format: YYYY-MM-DD
ReceiptsReceived If Y, then this report has its receipt receipt confirmed by the Expense Processor. Format: Y/N
ReportOwner This parent element includes details about the employee who is the report owner. It saves the caller from calling the Get User Information function to get employee information commonly used in accounting integration. The ReportOwner element includes the most recent information about the report owner, at the time the report is requested.
EmployeeBankAccount This parent element includes the bank account data found on the Bank Information page in Profile. This data is used in Payment System integrations where the payment system reimburses the employee via this bank account.

ExpenseEntry

Element Description
ReportEntryID The ID of the report entry. Maximum 13 characters.
ExpenseTypeID The expense type ID for the expense entry. Expense Type IDs are returned in the ExpKey element by the Get Expense Group Configuration endpoint.
ExpenseTypeName The expense type name. Maximum 64 characters.
SpendCategory The spend category specified for this expense type. Varies by client, used in reporting.
PaymentTypeCode The code for the payment type. Maximum 4 characters.
PaymentTypeName The name for the payment type. Maximum 80 characters.
TransactionDate The date of the expense entry. Maximum 10 characters. Format: YYYY-MM-DD
TransactionCurrencyName The name of the transaction currency. Example: US, Dollar
ExchangeRate The exchange rate that applies to the entry. Maximum 23 characters.
TransactionAmount The amount of the expense entry in the original transaction currency. Maximum 23 characters.
PostedAmount The amount of the expense entry in the user's reimbursement currency. The user's reimbursement currency is returned in the CrnCode element for the report. Maximum 23 characters.
ApprovedAmount The approved amount of the expense entry in the user's reimbursement currency.The user's reimbursement currency is returned in the CrnCode element for the report. Maximum 23 characters.
BusinessPurpose The text from the Business Purpose field of the entry. Maximum 64 characters.
VendorDescription The vendor name of the expense entry, which can be entered manually by the user or imported from the card transaction Merchant Name field. Maximum 64 characters.
LocationName The location for the expense entry, usually the city name.
LocationSubdivision The location's State, Province, or Country Subdivision. Maximum 6 characters.
LocationCountry The location's Country. Maximum 2 characters.
OrgUnit1 through OrgUnit6 The details from the Org Unit custom fields. These may not have data, depending on configuration. Maximum 48 characters for each field.
Custom1 through Custom40 The details from the Custom fields. These may not have data, depending on configuration. Refer to the Custom Fields elements table for more information.
FormID The ID for the expense entry form.
EntryImageID The unique identifier for the image associated with the entry.
HasVat Whether the entry contains VAT data. Maximum 1 character. Format: Y/N
HasComments Whether the expense entry has comments. Maximum 1 character. Format: Y/N
CommentCount The number of comments associated with the expense entry.
IsItemized Whether the expense entry is itemized. Maximum 1 character. Format: Y/N
HasExceptions Whether the expense entry has exceptions. Maximum 1 character. Format: Y/N
IsPersonal Whether the expense entry is marked as personal. Maximum 1 character. Format: Y/N
HasAttendees Whether the expense entry has attendees. Maximum 1 character. Format: Y/N
HasAllocation Defines the amount of allocations for the expense. Maximum 1 character. Possible values are: P, for partial allocation, F, for full allocation, or N, for no allocation.
IsCreditCardCharge Whether the expense came from a credit card feed. Maximum 1 character. Format: Y/N
IsPersonalCardCharge Whether the expense came from a personal card feed. Maximum 1 character. Format: Y/N
ReceiptRequired Whether the original receipt is required for the entry. Maximum 1 character. Format: Y/N
ImageRequired Whether a receipt image is required for the entry. Maximum 1 character. Format: Y/N
E-ReceiptID The ID for the attached e-receipt, if available.
LastModifiedDate The date the expense entry was last changed. Maximum 19 characters. Format: YYYY-MM-DDThh:mm:ss
ItemizationsList The list of itemizations for the expense entry. This parent element will have at least one Itemization child element. If the expense entry is not itemized, the Itemization will contain the same values as the entry. If the expense entry has itemizations, there will be one Itemization child element for each itemization. Refer to the Itemization elements table for more information.
NOTE: There are a few rare cases where the ItemizationsList will be null. This happens when a report entry has a payment type code that is not IBCP with offsets or CBCP and there is a Regular or Child expense entry with an Approved Amount equal to zero. The expense entry will have a Null ItemizationsList.
ReportEntryVendorName Vendor name the employee selected from the Vendor list field. Maximum 64 characters.
ReportEntryReceiptReceived If Y, then this entry has been marked as reviewed by a processor. Maximum 1 character. Format: Y/N
ReportEntryReceiptType Maximum 1 character. One of these:
T = tax receipt
R= regular receipt
N = no receipt
CardTransaction This parent element includes the card transaction data found in the card transaction associated to this expense entry. This data is used in Payment System integrations where the payment system reimburses the card issuer for the indicated card account. Refer to the CardTransaction elements table.
ExpensePay Whether the entry was paid using the Expense Pay service. This element has a value if the report has reached the Processing Payment workflow step. Format: Yes/No

Itemization

Element Description
ItemType The type of itemization. If the expense entry does not have any itemizations, this will be set to Regular. If the expense entry contains itemizations, each one will be set to Child.
ItemizationID The unique identifier for the itemization. Maximum 19 characters.
ExpenseTypeID The expense type ID for the itemization.
ExpenseTypeName The expense type for the itemization. Maximum 64 characters.
TransactionDate The date of the transaction. Maximum 10 characters. Format: YYYY-MM-DD
TransactionAmount The amount for the itemization in the expense currency. Maximum 23 characters.
PostedAmount The amount for the itemization in the user's reimbursement currency. The user's reimbursement currency is returned in the CrnCode element for the report. Maximum 23 characters.
ApprovedAmount The approved amount of the itemization in the user's reimbursement currency. The user's reimbursement currency is returned in the CrnCode element for the report. Maximum 23 characters.
BusinessPurpose The business purpose field from the report header.
OrgUnit1 through OrgUnit6 The details from the Org Unit custom fields. These may not have data, depending on configuration. Maximum 48 characters for each field.
Custom1 through Custom40 The custom fields associated with the itemization. These may not have data, depending on your configuration. Refer to the Custom Fields elements table for more information.
Value The value in the custom field. Maximum 48 characters.
Code Custom list fields will include the list item code in this element.
HasComments Whether the itemization has comments. Maximum 1 character. Format: Y/N
CommentCount The number of comments associated with the itemization.
IsPersonal Whether the itemization is personal. Maximum 1 character. Format: Y/N
LastModified The UTC date when the itemization was last modified. Maximum 19 characters. Format: YYYY-MM-DDThh:mm:ss
AttendeesList This parent element contains one Attendee element for each associated attendee. Refer to the Attendee elements table for more information.
AllocationsList This parent element contains at least one Allocation element. It will contain multiple Allocation elements if there are multiple allocations for the itemization. Refer to the Allocation elements table.

Attendee

Element Description
AttendeeType The type of attendee. Maximum 40 characters.
FirstName The attendee's first name. Maximum 50 characters.
LastName The attendee's last name. Maximum 132 characters.
Company The attendee's company name. Maximum 150 characters.
Title The attendee's title. Maximum 32 characters.
ExternalID The unique identifier for the attendee, managed outside SAP Concur. Maximum 48 characters.
Custom1 through Custom20 The details from the custom fields. These may not have data, depending on configuration. Refer to the Custom Fields elements table for more information.
HasExceptionsPrevYear Whether the attendee has exceptions in the previous year, based on yearly total limits for attendees. Maximum 1 character. Format: Y/N
HasExceptionsYTD Whether the attendee has exceptions in the current year, based on yearly total limits for attendees. Maximum 1 character. Format: Y/N
IsDeleted Whether the attendee is marked as deleted. Maximum 1 character. Format: Y/N
OwnerName The name of the employee that owns the attendee record.
TotalAmountPrevYear The total amount spent on the attendee in the previous calendar year.
TotalAmountYTD The total amount spent on the attendee in the current calendar year.
VersionNumber The attendee's version number.
AttendeeID Attendee unique identifier within SAP Concur.
AttendeeTypeCode The unique identifier for the attendee type.
AttendeeOwnerID The unique identifier for the person or system that owns the attendee.
CurrencyCode The 3-letter ISO 4217 currency code for attendee related amounts.

Allocation

Element Description
AllocationID The unique alphanumeric identifier for the allocation. Maximum 13 characters.
Percentage The percentage of the expense that is included in this allocation. Maximum 11 characters.
AccountCode1 The primary accounting code assigned to the expense type associated with this allocation. Typically, expense types have only this primary account code.
AccountCode2 The secondary or alternative accounting code assigned to the expense type associated with this allocation. In rare cases some expense types include this accounting code to handle special cases. One example of these special cases is when using travel allowance, where one expense would use the primary account code for the allowed amount, and the alternative account code for the overage. Another example is personal use of a company car.
Refer to the Expense: Account Codes Setup Guide for more information on how Concur Expense determines which accounting codes to use.
Custom1 through Custom20 The custom fields associated with the allocation. These may not have data, depending on your configuration. Refer to the Custom Fields elements table for more information.
JournalEntriesList This parent element contains at least one JournalEntry child element. It contains multiple JournalEntry elements if the allocation has multiple journal entries. Refer to the JournalEntry elements table for more information.
VATDataList This parent element contains one VATData element for each VAT line item. This element will be empty if there are no VAT line items. Refer to the VATData elements table for more information.

JournalEntry

Element Description
JournalID Unique identifier for the journal entry.
PayerPaymentTypeName Payer payment type. Maximum 64 characters. One of these:
Company = Company
Employee = Employee
Payment Type for the Credit Card Payment Type
PayerPaymentTypeCode Payment code name for the payer. Maximum 80 characters.
PayeePaymentTypeName Payee payment type. Maximum 64 characters. One of these:
Company = Company
Employee = Employee
Payment Type for the Credit Card Payment Type
PayeePaymentCode Payment code name for the payee. Maximum 80 characters.
AccountCode The account code Concur Expense determines should apply to this journal entry. For journal entries associated to an allocation, Concur Expense uses the business logic described in the Expense: Account Codes Setup Guide to determine whether the primary or secondary account code should apply.  When there is no allocation associated to the journal entry, Concur Expense uses clearing account codes for Credit Card and Cash Advance for personal use of a company paid expense or a cash advance issued to an employee respectively. Maximum 48 characters.
NOTE: The developer should almost always use this accounting code when creating financial transactions in financial systems. In some situations a developer may need to use the accounting codes in the Allocation parent element.
DebitOrCredit Maximum 2 characters. Either:
DR = Debit
CR = Credit
Amount Value, as credit or debit, of the amount to be exchanged between the payer and payee for this expense account code (not an absolute value) Maximum 23 characters. EXAMPLES: Value of zero, credit, or debit, as the following:
0 (Zero) "0"
+ (Plus / Debit) "+50.00"
- (Minus / Credit) "-50.00"
JobRunKey Either the unique identifier for job run for the accounting extract that processed this journal, or a static value indicating the journal was processed by Manual Pay, Expense Pay, or some other system.

VATData

Element Description
TaxName Tax authority name. Maximum 50 characters.
TaxAuthorityLabel 5-digit code that appears on the expense entry pages. Maximum 5 characters.
TaxTransactionAmount Calculated tax amount for this expense in the spend currency. Maximum 23 characters.
TaxPostedAmount Calculated tax amount for this expense entry in the reimbursement currency. Maximum 23 characters.
Source Specifies how the tax data was derived. Maximum 4 characters. One of these:
CARD = Provided from company card
USER = Entered by employee
SYST = Calculated by system
PROC = Entered by processor
TaxReclaimTransactionAmount Calculated amount of tax eligible for reclaim in the spend currency. Maximum 23 characters.
TaxReclaimPostedAmount Calculated amount of tax eligible for reclaim in the reimbursement currency. Maximum 23 characters.

CardTransaction

Element Description
AccountNumber Credit card number used for this expense. This value is encrypted in the response. Maximum 255 characters.
CardDescription The name on the credit card used for this expense. Maximum 255 characters.
CardTypeCode Type of credit card.
TransactionReferenceNumber Reference number from the credit card vendor. Maximum 64 characters.
TransactionCCTType Transaction type supplied by card vendor. Maximum 3 characters. One of these:
ANF = Annual Fees
CAV = Cash Advance
CCF = Cash and Check Fees
CHG = Other Bank Charges and Fees
FNC = Finance Charges
LAF = Late Fees
NSF = Insufficient Funds Check Fees
PAY = Payment
RPE = Credit Card Transaction
TransactionID Calculated value assigned to this card entry during the import process. Maximum 32 characters.
TransactionAmount Amount of the charge in the spend currency. Maximum 23 characters.
TaxAmount Amount of tax on the transaction amount (if provided by card vendor). Maximum 23 characters.
TransactionAlphaCode Currency code for the spend currency. Maximum 3 characters. Format: ISO 4217 3 digit alpha code
PostedAmount Amount of the charge in the billing currency of the card. Maximum 23 characters.
PostedAlphaCode Currency code for the card billing currency. Maximum 3 characters. Format: ISO 4217 3 digit alpha code
TransactionDate Date the charge was made at the merchant. Maximum 10 characters.
PostedDate Date the charge was posted to the credit card account. Maximum 10 characters.
Description Description of the charge from the merchant. Maximum 42 characters.
MasterCardCode Merchant code sent from the credit card vendor. Maximum 5 characters.
TransactionMerchantName Name of the merchant. Maximum 50 characters.
MerchantCity Merchant city. Maximum 40 characters.
MerchantState Merchant State/Province. Maximum 32 characters.
MerchantCountryCode Merchant country location code. Format: 2 digit alpha code
MerchantReferenceNumber Merchant reference number passed from the merchant to the card. Maximum 15 characters.
ExchangeRateFromBillingToEmployeeCurrency Currency exchange rate used between the credit card billing currency and the employee's reimbursement currency. Maximum 23 characters.
BillingAmount Amount due to the company card from the employee or company (depending on who is responsible for the bill) for this detail row. Maximum 23 characters.
AccountNumberLastSegment The last 4 digits of the Card Account.

Custom Fields

Element Description
Type The custom field type. Will be one of the following: Amount, Boolean, ConnectedList, Date, Integer, List, Number, Text
Value The value in the custom field. Maximum 48 characters.
Code Custom list fields will include the list item code in this element.

ReportOwner

Element Description
EmployeeCustom21 The report owner's group ID. Maximum 48 characters.
EmployeeID Employee ID often also serves as the employee's Vendor ID for AP system integrations or Payroll ID for Payroll integrations. Maximum 48 characters.
EmployeeOrgUnit1 through EmployeeOrgUnit6 The report owner's organizational unit information. Maximum 48 characters for each field.
FirstName The report owner's first name. Maximum 32 characters.
LastName The report owner's last name. Maximum 32 characters.
MiddleInitial The report owner's middle initial. Maximum 1 character.
ReimbursementMethodCode The report owner's reimbursement method code, as defined in the employee's Profile.

EmployeeBankAccount

Element Description
BankNumber The bank identification number entered on the Bank Information page. Maximum 11 characters.
BankName The bank name entered on the Bank Information page. Maximum 48 characters.
BranchLocation The branch location entered on the Bank Information page. Maximum 30 characters.
AccountNumber The bank account number entered on the Bank Information page. Maximum 100 characters.
AccountName The name on the account entered on the Bank Information page.
PostalAddressLine1 The postal address line 1 entered on the Bank Information page. Maximum 48 characters.
PostalAddressLine2 The postal address line 2 entered on the Bank Information page. Maximum 48 characters.
PostalAddressCity The postal address city entered on the Bank Information page. Maximum 24 characters.
PostalAddressRegion The postal address region entered on the Bank Information page. Maximum 24 characters.
PostalAddressCode The postal address code entered on the Bank Information page. Maximum 20 characters.
PostalAddressCountry The postal address country entered on the Bank Information page. Maximum 2 characters. Format: The ISO 3166-1 alpha-2 country code. Example: United States is US.

Examples

XML Example Request

GET https://us.api.concursolutions.com/api/expense/expensereport/v2.0/report/n6ujbuLd1Arwe45lT7As3ThJYJf2dAsrrEW HTTP/1.1
Authorization: OAuth {access token}
...

XML Example of Successful Response

HTTP/1.1 200 OK
Content-Type: application/xml

<?xml version="1.0" encoding="utf-8"?>
<ReportDetails xmlns="http://us.api.concursolutions.com/api/expense/expensereport/2012/07" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
    <UserLoginID>cm@example.com</UserLoginID>
    <EmployeeName>Miller, Chris</EmployeeName>
    <ReportID>425FE2ADB4954FCA90CD</ReportID>
    <ReportName>Client Meeting</ReportName>
    <Purpose>Sales meeting</Purpose>
    <ReportDate>2013-01-10T00:00:00</ReportDate>
    <CreationDate>2013-01-11T01:58:20</CreationDate>
    <SubmitDate>0001-01-01T00:00:00</SubmitDate>
    <PaidDate i:nil="true" />
    <CurrencyCode>USD</CurrencyCode>
    <ReportTotal>50.00000000</ReportTotal>
    <PersonalExpenses>0.00000000</PersonalExpenses>
    <AmountDueEmployee>50.00000000</AmountDueEmployee>
    <AmountDueCompanyCard>0.00000000</AmountDueCompanyCard>
    <TotalClaimedAmount>50.00000000</TotalClaimedAmount>
    <TotalApprovedAmount>50.00000000</TotalApprovedAmount>
    <ApprovalStatusCode>A_NOTF</ApprovalStatusCode>
    <ApprovalStatusName>Not Submitted</ApprovalStatusName>
    <PaymentStatusCode>P_NOTP</PaymentStatusCode>
    <PaymentStatusName>Not Paid</PaymentStatusName>
    <OrgUnit1>Sales</OrgUnit1>
    <OrgUnit2 />
    <OrgUnit3 />
    <OrgUnit4 />
    <OrgUnit5 />
    <OrgUnit6 />
    <Custom1 />
    <Custom2 />
    <Custom3 />
    <Custom4 />
    <Custom5 />
    <Custom6 />
    <Custom7 />
    <Custom8 />
    <Custom9 />
    <Custom10 />
    <Custom11 />
    <Custom12 />
    <Custom13 />
    <Custom14 />
    <Custom15 />
    <Custom16 />
    <Custom17 />
    <Custom18 />
    <Custom19 />
    <Custom20 />
    <LedgerName>Corporate</LedgerName>
    <PolicyID>ndrF8hjzl9FtFUdfaBwVvXP$sD1vDpRKNf</PolicyID>
    <EverSentBack>N</EverSentBack>
    <HasException>N</HasException>
    <WorkflowActionURL />
    <ExpenseEntriesList>
        <ExpenseEntry>
            <ReportEntryID>nE0avYnILN9mHdTErNSd2pH45udFoNQ$po</ReportEntryID>
            <ExpenseTypeID>BUSML</ExpenseTypeID>
            <ExpenseTypeName>Business Meal (attendees)</ExpenseTypeName>
            <SpendCategory>Entertainment</SpendCategory>
            <PaymentTypeCode>CASH</PaymentTypeCode>
            <PaymentTypeName>Cash</PaymentTypeName>
            <TransactionDate>2013-01-10T00:00:00</TransactionDate>
            <TransactionCurrencyName>US, Dollar</TransactionCurrencyName>
            <ExchangeRate>1.00000000000000</ExchangeRate>
            <TransactionAmount>50.00000000</TransactionAmount>
            <PostedAmount>50.00000000</PostedAmount>
            <ApprovedAmount />
            <BusinessPurpose />
            <VendorDescription />
            <LocationName>Washington</LocationName>
            <LocationSubdivision>US-DC</LocationSubdivision>
            <LocationCountry>US</LocationCountry>
            <OrgUnit1>Sales</OrgUnit1>
            <OrgUnit2 />
            <OrgUnit3 />
            <OrgUnit4 />
            <OrgUnit5 />
            <OrgUnit6 />
            <Custom1 />
            <Custom2 />
            <Custom3 />
            <Custom4 />
            <Custom5 />
            <Custom6 />
            <Custom7 />
            <Custom8 />
            <Custom9 />
            <Custom10 />
            <Custom11 />
            <Custom12 />
            <Custom13 />
            <Custom14 />
            <Custom15 />
            <Custom16 />
            <Custom17 />
            <Custom18 />
            <Custom19 />
            <Custom20 />
            <Custom21 />
            <Custom22 />
            <Custom23 />
            <Custom24 />
            <Custom25 />
            <Custom26 />
            <Custom27 />
            <Custom28 />
            <Custom29 />
            <Custom30 />
            <Custom31 />
            <Custom32 />
            <Custom33 />
            <Custom34 />
            <Custom35 />
            <Custom36 />
            <Custom37 />
            <Custom38 />
            <Custom39 />
            <Custom40 />
            <FormID>nAaT8$puKKOhs7h2wespCW7vyyxJAJcyb5</FormID>
            <EntryImageID />
            <HasVat>N</HasVat>
            <HasComments>N</HasComments>
            <CommentCount>0</CommentCount>
            <IsItemized>Y</IsItemized>
            <HasExceptions>N</HasExceptions>
            <IsPersonal>N</IsPersonal>
            <HasAttendees>Y</HasAttendees>
            <HasAllocation>N</HasAllocation>
            <IsCreditCardCharge>N</IsCreditCardCharge>
            <IsPersonalCardCharge>N</IsPersonalCardCharge>
            <ReceiptRequired>N</ReceiptRequired>
            <ImageRequired>N</ImageRequired>
            <E-ReceiptID />
            <LastModified>2013-01-11T01:59:52</LastModified>
            <ItemizationsList>
                <Itemization>
                    <ItemType>Regular</ItemType>
                    <ItemizationID>nE0avYnILN9mHdTErNSd2pH45udFoNQ$po</ItemizationID>
                    <ExpenseTypeID>BUSML</ExpenseTypeID>
                    <ExpenseTypeName>Business Meal (attendees)</ExpenseTypeName>
                    <TransactionDate>2013-01-10T00:00:00</TransactionDate>
                    <TransactionAmount>50.00000000</TransactionAmount>
                    <PostedAmount>50.00000000</PostedAmount>
                    <ApprovedAmount />
                    <BusinessPurpose />
                    <OrgUnit1>Sales</OrgUnit1>
                    <OrgUnit2 />
                    <OrgUnit3 />
                    <OrgUnit4 />
                    <OrgUnit5 />
                    <OrgUnit6 />
                    <Custom1 />
                    <Custom2 />
                    <Custom3 />
                    <Custom4 />
                    <Custom5 />
                    <Custom6 />
                    <Custom7 />
                    <Custom8 />
                    <Custom9 />
                    <Custom10 />
                    <Custom11 />
                    <Custom12 />
                    <Custom13 />
                    <Custom14 />
                    <Custom15 />
                    <Custom16 />
                    <Custom17 />
                    <Custom18 />
                    <Custom19 />
                    <Custom20 />
                    <Custom21 />
                    <Custom22 />
                    <Custom23 />
                    <Custom24 />
                    <Custom25 />
                    <Custom26 />
                    <Custom27 />
                    <Custom28 />
                    <Custom29 />
                    <Custom30 />
                    <Custom31 />
                    <Custom32 />
                    <Custom33 />
                    <Custom34 />
                    <Custom35 />
                    <Custom36 />
                    <Custom37 />
                    <Custom38 />
                    <Custom39 />
                    <Custom40 />
                    <HasComments>N</HasComments>
                    <CommentCount>0</CommentCount>
                    <IsPersonal>N</IsPersonal>
                    <LastModified>2013-01-11T01:59:52</LastModified>
                    <AllocationsList />
                    <AttendeesList>
                        <Attendee>
                            <AttendeeType>BUSGUEST</AttendeeType>
                            <FirstName>Pat</FirstName>
                            <LastName>Davis</LastName>
                            <Company />
                            <Title />
                            <ExternalID />
                            <Custom1 />
                            <Custom2 />
                            <Custom3 />
                            <Custom4 />
                            <Custom5 />
                            <Custom6 />
                            <Custom7 />
                            <Custom8 />
                            <Custom9 />
                            <Custom10 />
                            <Custom11 />
                            <Custom12 />
                            <Custom13 />
                            <Custom14 />
                            <Custom15 />
                            <Custom16 />
                            <Custom17 />
                            <Custom18 />
                            <Custom19 />
                            <Custom20 />
                            <HasExceptionsPrevYear>N</HasExceptionsPrevYear>
                            <HasExceptionsYTD>N</HasExceptionsYTD>
                            <IsDeleted>N</IsDeleted>
                            <OwnerEmpName>Miller, Chris</OwnerEmpName>
                            <TotalAmountPrevYear>0.00000000</TotalAmountPrevYear>
                            <TotalAmountYTD>0.00000000</TotalAmountYTD>
                            <VersionNumber>1</VersionNumber>
                            <AttendeeID>nFaAj038Hw$plfUD8be0I45wTx8$sMlTd$pP</AttendeeID>
                            <AttendeeTypeCode>BUSGUEST</AttendeeTypeCode>
                            <AttendeeOwnerID>cm@example.com</AttendeeOwnerID>
                            <CurrencyCode>USD</CurrencyCode>
                        </Attendee>
                    </AttendeesList>
                </Itemization>
                <Itemization>
                    <ItemType>Child</ItemType>
                    <ItemizationID>nE0avYnILN9g$s6lCFX0jFBWmHAiTYYf9C</ItemizationID>
                    <ExpenseTypeID>BRKFT</ExpenseTypeID>
                    <ExpenseTypeName>Breakfast</ExpenseTypeName>
                    <TransactionDate>2013-01-10T00:00:00</TransactionDate>
                    <TransactionAmount>50.00000000</TransactionAmount>
                    <PostedAmount>50.00000000</PostedAmount>
                    <ApprovedAmount>50.00000000</ApprovedAmount>
                    <BusinessPurpose />
                    <OrgUnit1>Sales</OrgUnit1>
                    <OrgUnit2 />
                    <OrgUnit3 />
                    <OrgUnit4 />
                    <OrgUnit5 />
                    <OrgUnit6 />
                    <Custom1 />
                    <Custom2 />
                    <Custom3 />
                    <Custom4 />
                    <Custom5 />
                    <Custom6 />
                    <Custom7 />
                    <Custom8 />
                    <Custom9 />
                    <Custom10 />
                    <Custom11 />
                    <Custom12 />
                    <Custom13 />
                    <Custom14 />
                    <Custom15 />
                    <Custom16 />
                    <Custom17 />
                    <Custom18 />
                    <Custom19 />
                    <Custom20 />
                    <Custom21 />
                    <Custom22 />
                    <Custom23 />
                    <Custom24 />
                    <Custom25 />
                    <Custom26 />
                    <Custom27 />
                    <Custom28 />
                    <Custom29 />
                    <Custom30 />
                    <Custom31 />
                    <Custom32 />
                    <Custom33 />
                    <Custom34 />
                    <Custom35 />
                    <Custom36 />
                    <Custom37 />
                    <Custom38 />
                    <Custom39 />
                    <Custom40 />
                    <HasComments>N</HasComments>
                    <CommentCount>0</CommentCount>
                    <IsPersonal>N</IsPersonal>
                    <LastModified>2013-01-11T01:59:52</LastModified>
                    <AllocationsList>
                        <Allocation>
                            <AllocationID>ngYn5SB4OUXgRV6P8VgsQQr88SaKYvbqz</AllocationID>
                            <Percentage>100.00000000%</Percentage>
                            <AccountCode1>AC_BRKFT1</AccountCode1>
                            <AccountCode2>AC_BRKFT2</AccountCode2>
                            <Custom1 />
                            <Custom2 />
                            <Custom3 />
                            <Custom4 />
                            <Custom5 />
                            <Custom6 />
                            <Custom7 />
                            <Custom8 />
                            <Custom9 />
                            <Custom10 />
                            <Custom11 />
                            <Custom12 />
                            <Custom13 />
                            <Custom14 />
                            <Custom15 />
                            <Custom16 />
                            <Custom17 />
                            <Custom18 />
                            <Custom19 />
                            <Custom20 />
                            <VATDataList />
                        </Allocation>
                    </AllocationsList>
                    <AttendeesList />
                </Itemization>
            </ItemizationsList>
            <UserLoginID>cm@example.com</UserLoginID>
        </ExpenseEntry>
    </ExpenseEntriesList>
    <Country>US</Country>
    <CountrySubdivision></CountrySubdivision>
    <ProcessingPaymentDate></ProcessingPaymentDate>
    <ReceiptsReceived>Y</ReceiptsReceived>
    <ReportOwner>
        <EmployeeID>cm@example.com</EmployeeID>
        <LastName>Chris</LastName>
        <FirstName>Miller</FirstName>
        <MiddleInitial></MiddleInitial>
        <EmployeeCustom21></EmployeeCustom21>
        <EmployeeOrgUnit1></EmployeeOrgUnit1>
        <EmployeeOrgUnit2></EmployeeOrgUnit2>
        <EmployeeOrgUnit3></EmployeeOrgUnit3>
        <EmployeeOrgUnit4></EmployeeOrgUnit4>
        <EmployeeOrgUnit5></EmployeeOrgUnit5>
        <EmployeeOrgUnit6></EmployeeOrgUnit6>
        <ReimbursementMethodCode>CNQRPAY</ReimbursementMethodCode>
    </ReportOwner>
</ReportDetails>

Integration Status

The integration status of the supplied object. Currently supports expense reports.

This resource allows developers to ensure that the necessary transactions to account for expenses and arrange payment for the expenses in a specified report were created in the financial system prior to committing the expense report in Concur Expense. If they were, the developer uses this function to indicate the report was successfully integrated and move the report forward in the workflow to the Paid step. In Concur Expense, when a report arrives at the Paid workflow step the report is committed, meaning its data can't be changed and it can't be sent back in the workflow.

URI

https://www.concursolutions.com/api/expense/expensereport/v2.0/integrationstatus/

Operations

POST

Request

Request Parameters

Path Parameters

Parameter Required/Optional Description
report/{ReportID} required The report keyword and the ReportID for the report that has been successfully integrated into the financial system. The ReportID is returned in the ReportID element by the Get List of Reports and the Get Report Details responses.

Headers

Authorization Header

Authorization header with OAuth token for valid SAP Concur user. Required. The OAuth consumer must have the following user role: Web Services Administrator

Content-Type Header

Response

Content Types

Schema

The response will include an ActionStatus parent element (XML), or an object (JSON) with the following child elements (XML) or name/value pairs (JSON).

ActionStatus elements

Element Description
Status Whether the request was successful. Possible values: SUCCESS, FAILURE.
Message Provides further details for errors.

Examples

XML Example Request

POST https://www.concursolutions.com/api/expense/expensereport/v2.0/integrationstatus/report/nx2WRNzp18$wjehk%wqEL6EDHRwi9r$paQS1UqyL6a454QitqQ HTTP/1.1
Authorization: OAuth {access token}
Accept: application/xml
...

XML Example of Successful Response

HTTP/1.1 200 OK
Content-Type: application/xml

<ActionStatus xmlns="http://www.concursolutions.com/api/expense/expensereport/2011/03" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
    <Message>SUCCESS</Message>
    <Status>SUCCESS</Status>
</ActionStatus>

JSON Example of Successful Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "Status": "SUCCESS",
  "Message": "SUCCESS"
}

JSON Example of Response with Error

HTTP/1.1 200 OK
Content-Type: application/json

{
  "Status": "FAILURE",
  "Message": "To use the POST Expense Journal Entry Job Key the report must be at the Processing Payment or Payment Confirmed Payment Status."
}

Create an exception to a report

Posts an exception to the report, and associates it with one of the following data levels: Report Header, Entry, Itemization, Allocation. This endpoint requires familiarity with the company's exception code configuration.

Request

Request Parameters

Path Parameters

Parameter Required/Optional Description
{reportKey}/Exceptions required The identifier for the desired report and the exceptions keyword.

Example: https://www.concursolutions.com/api/expense/expensereport/v1.1/report/{reportKey}/Exceptions

URI Source: The reportKey value is returned in the RptKey element by the Get Report Details response.

Headers

Authorization Header

Authorization header with OAuth token for valid SAP Concur user. Required.

Content-Type Header

application/xml

Request Schema

This request should contain an Exceptions parent element with an Exception parent element for each exception included in the report. The Exception element contains the following child elements:

Exception Elements

Element Required (must contain value)? Description
Index Y The exception's location in a batch of exceptions. Should start at 1 and increment sequentially. This value is used to identify the record if there is an error.
ObjectType Y The type of object to assign the exception. Format: Report, Entry, or Allocation. When sending a Report level exception, the ObjectType and ObjectId can be null, as the report key is supplied in the URI.
ObjectId Y The unique identifier for the object to associate with the exception. Returned by the Get Report Details function. Must be the value from one of the following fields:
   Entry or Itemization: Use the RpeKey.
   Allocation: Use AllocationKey.
   Report Header: Null value. When sending a Report level exception, the ObjectType and ObjectId can be null, as the report key is supplied in the URI.
ExceptionCode Y The Exception Code for the exception to assign to the object. Must be a configured exception code in Expense. Example: NODATE

Response

Content Types

application/xml

Response Schema

This request will return an exception-result parent element.

Exception-Result Elements

Element Description
exceptions-succeeded The number of exceptions processed that were successfully assigned.
exceptions-failed The number of exceptions processed that were not successfully added.
errors This will contain an error parent element for each record failure. The error element will contain the following child elements:
   Index: The exception's location in the batch.
   message: The error message.
ExceptionDetails This parent element will contain an ExceptionInfo parent element for all exceptions that did not cause an error, and will contain the following child elements:
   Index: The exception's location in the batch.
   Status: The status of the request.

Examples

XML Example Request

POST https://www.concursolutions.com/api/expense/expensereport/v1.1/report/3FK118eIJ844Uwl0HF32/Exceptions HTTP/1.1
Authorization: OAuth {access token}
Content-Type: application/xml

<Exceptions xmlns="http://www.concursolutions.com/api/expense/expensereport/2011/03" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
    <Exception>
        <Index>1</Index>
        <ObjectType>Report</ObjectType>
        <ObjectId>nxxKgLlnRODp$sie8Hq1UviOJ2AbpS7dCP</ObjectId>
        <ExceptionCode>APPRVTO</ExceptionCode>
    </Exception>
    <Exception>
        <Index>2</Index>
        <ObjectType>Entry</ObjectType>
        <ObjectId>nxxKgLlnRODp$sie8Hq1UviOJ2deAbpS7dC0</ObjectId>
        <ExceptionCode>APPRVTO</ExceptionCode>
    </Exception>
</Exceptions>

XML Example of Response With Success and Failure

<exception-result xmlns="http://www.concursolutions.com/api/expense/expensereport/2011/03" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
    <exceptions-succeeded>1</exceptions-succeeded>
    <exceptions-failed>1</exceptions-failed>
    <errors>
        <error>
            <Index>2</Index>
            <message>Invalid Exception Code</message>
        </error>
    </errors>
    <ExceptionDetails>
        <ExceptionInfo>
            <Index>1</Index>
            <Status>Success</Status>
        </ExceptionInfo>
    </ExceptionDetails>
</exception-result>

Submit an expense report

Triggers the Submit workflow action for the specified report.

Important Note: This endpoint submits the expense report as if the original report owner had submitted it. Consult your company's Expense administrator to confirm that the web service should be allowed to submit reports on behalf of users. If you wish to enforce the expense report delegate functionality, use the Get Expense Delegators function to determine if the user in question has the correct permissions to submit on behalf of the report owner.

Request

Request Parameters

Path Parameters

Parameter Required/Optional Description
{reportKEY}/submit required The identifier for the desired report and the submit keyword.

Example: https://www.concursolutions.com/api/expense/expensereport/v1.1/report/{reportKEY}/submit

URI Source: The reportId value is returned by the Get List of Reports and Get Report Details functions, and as part of the Report-Details-Url element of the Post Expense Report Header function.

Content Types

application/xml

Authorization Header

Authorization: This request requires an Authorization header with an OAuth token for a valid SAP Concur user.

X_UserID: This request requires an additional field in the authorization header, identifying the report owner. This identifier is the SAP Concur login for the user, and is often also the email address of the user. The field format is:
X_UserID: expenseuser@example.com

Response

Schema

This request will return a ReportStatus parent element with the following child elements.

Report Status Elements

Element Description
Message The error message. Only appears if a submission error was generated.
Status The status of the report submit action.

If the report submission triggered an exception, a ReportExceptions parent element will be provided, with a ReportException parent element for each exception. The ReportException element contains the following elements.

Report Exception Schema

Element Description
CrnCode The currency code of the entry.
EventCode The event that resulted in the exception.
ExceptionCode The company-defined exception code.
ExceptionErrorCode The severity of the exception. Exceptions with ERROR as the code cannot be submitted.
ExceptionVisibility Which users are able to see the exception.
ExpKey The expense type key for the entry.
ExpName The expense type name for the entry.
IsCleared Whether the exception has been cleared by the Expense Processor.
SeverityLevel A numeric value indicating the severity level of the exception. The value threshold is configurable.
TransactionAmount The amount of the entry.
TransactionDate The date of the entry.
Type The exception type.

Examples

XML Example Request

POST https://www.concursolutions.com/api/expense/expensereport/v1.1/report/nxxKgLlnROz$sQ6SKJFjLNs4OWBErcJ8yX/submit HTTP/1.1
Authorization: OAuth {access token}
X-UserID: cmiller@example.com
...

XML example of Successful Response

<ReportStatus xmlns="http://www.concursolutions.com/api/expense/expensereport/2011/03" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
    <Status>SUCCESS</Status>
</ReportStatus>

Post an expense report workflow action

Posts a workflow action for the supplied expense report. The workflow action moves the expense report through the workflow process.

Workflow Actions

The available actions are:

WARNING: Prior to calling this endpoint the Caller must check the Approval Status found in the ApprovalStatusName element in the response for Get Report Details to ensure the report is at the workflow step the Caller expects.  Under no circumstance should a Caller make a call to this endpoint without being certain the report is at the workflow step the Caller expects.

Workflow Roles

Each workflow step in a workflow is associated with a workflow role. Professional clients can configure workflow steps and roles in the Workflows area of Expense Admin. The OAuth consumer is evaluated to determine which role(s) the consumer has in SAP Concur. There are two different types of workflow roles as described in the following sections.

System Role

The System role is used when the workflow actions can be completed programatically. Any workflow action can be completed this way, depending on the client's business process. The workflow role can be configured while adding the report workflow step. Some steps may require the System role. When using this role, the OAuth consumer must have the following user role:

The expense report owner must have an approver or processor assigned to them before the System role can make changes to their reports.

Approver Role

The Approver role is used when the workflow action should be completed by a particular user. Developers who want to present a list of reports to approve and send the workflow action when the reports have been evaluated by the approver use the Approver role. This role requires that a user with the correct SAP Concur role (Expense Approver, Authorized Approver, Cost Object Approver, or Expense Processor for Professional, or the Can Administer or Can Approve Reports roles for Standard) authenticates using Standard OAuth before supplying the workflow action. The user must also have access (be a valid approver or processor) for the supplied report ID.

Request

Request Parameters

Path Parameters

Parameter Required/Optional Description
{workflowstepID}/workflowaction required The identifier for the desired workflow step and the workflowaction keyword.

Example: https://www.concursolutions.com/api/expense/expensereport/v1.1/report/{workflowstepId}/workflowaction

URI Source: The URI is returned in the WorkflowActionURL element of the Get Report Details response.

Headers

Authorization Header

Authorization header with OAuth token for valid SAP Concur user. Required.

Content-Type Header

application/xml

Request Body

Request Schema

This request should contain a WorkflowAction parent element with the following child elements.

WorkflowAction Child Elements

Element Required/optional Description
Action required The name of the workflow action. Possible values are: Approve, Send Back to Employee, or Recall to Employee. Must be one of the workflow actions available for the workflow step. Consult Expense Admin > Workflow to learn details.
Comment required, for Send Back to Employee Must be used with the Send Back to Employee workflow action. This comment is visible wherever report comments are available to the employee, approver, authorization request administrator, and/or processor. Max length: 2000

Response

Response Schema

This request will return an ActionStatus parent element with the following child elements.

ActionStatus Elements

Element Description
Message The error message. Only appears if a workflow action error was generated.
Status The status of the report workflow action.

Examples

XML Example Request

POST https://www.concursolutions.com/api/expense/expensereport/v1.1/report/nx2WRNzp18$wjehk%wqEL6EDHRwi9r$paQS1UqyL6a454QitqQ/workflowaction HTTP/1.1
Authorization: OAuth {access token}
...

<WorkflowAction xmlns="http://www.concursolutions.com/api/expense/expensereport/2011/03">
    <Action>Approve</Action>
    <Comment>Approved via SAP Concur</Comment>
</WorkflowAction>

XML Example of Successful Response

<?xml version="1.0" encoding="utf-8"?>
<ActionStatus xmlns="http://www.concursolutions.com/api/expense/expensereport/2011/03" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
    <Message>SUCCESS!</Message>
    <Status>SUCCESS!</Status>
</ActionStatus>

XML Example of Response with Error

<?xml version="1.0" encoding="utf-8"?>
<ActionStatus xmlns="http://www.concursolutions.com/api/expense/expensereport/2011/03" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
    <Message>The action cannot be executed because the item has recently been changed. Please refresh your list and try again.</Message>
    <Status>FAILURE</Status>
</ActionStatus>

Expense Entry Attendee v3

Prior Versions

2.0 documentation is available here.

Retrieve All Entry-Attendee Associations Owned by the User

GET /api/v3.0/expense/entryattendeeassociations

Parameters

Name Type Format Description
entryID string query The ID of the entry for which to retrieve entry-attendee associations.
offset string query The starting point of the next set of results, after the limit specified in the limit field has been reached.
limit Int32 query The number of records to return. Default value: 25
user string query The login ID of the user who owns this entry-attendee association. The user must have the Web Services Admin role to use this parameter.

Request URL

https://www.concursolutions.com/api/v3.0/expense/entryattendeeassociations?limit=15&user=ALL

JSON Example of a Successful Response

{
  "Items": [
    {
      "EntryID": "gWidFO7ikXS264Tf3Z68NmcXdkxhcxezfzA",
      "AttendeeID": "gWj3IHRYiHZGX4xP$s0YUWUyoUjss$pWV3z$pQ",
      "Amount": 80,
      "AssociatedAttendeeCount": 1,
      "Custom1": null,
      "Custom2": null,
      "Custom3": null,
      "Custom4": null,
      "Custom5": null,
      "ID": "gWgSNsCedFvv8LE1LrkughW9mAyCN",
      "URI": "https://www.concursolutions.com/api/v3.0/expense/entryattendeeassociations/gWgSNsCedFvv8LE1LrkughW9mAyCN"
    },
    {
      "EntryID": "gWidFO7ikXSi7DX4hlLTggJD76w1IvtEvWw",
      "AttendeeID": "gWj3IHRYiHZGSG6M4xo0PEyYXAs8rHGfD$pQ",
      "Amount": 120,
      "AssociatedAttendeeCount": 1,
      "Custom1": null,
      "Custom2": null,
      "Custom3": null,
      "Custom4": null,
      "Custom5": null,
      "ID": "gWgOOsCJrozFymvWtfB5Ri1WD$ste9",
      "URI": "https://www.concursolutions.com/api/v3.0/expense/entryattendeeassociations/gWgOOsCJrozFymvWtfB5Ri1WD$ste9"
    }
  ]
}

Retrieve an Entry-Attendee Association by ID

GET /api/v3.0/expense/entryattendeeassociations/{id}

Parameters

Name Type Format Description
id string path Required The ID of the entry-attendee association.
user string query The login ID of the user who owns this entry-attendee association. The user must have the Web Services Admin role to use this parameter.

Request URL

https://www.concursolutions.com/api/v3.0/expense/entryattendeeassociations/gWgSM%24s2kvfcQ8xC%24p6uaPsY6V6qB7FqOU

JSON Example of a Successful Response

{
  "EntryID": "gWidFO7ikXV67u6QrT2w1Yhqzh4a8j$pEjCg",
  "AttendeeID": "gWj3IHRYiHZOTjq8PONWIqyRFfGz4RoozoQ",
  "Amount": 17.01,
  "AssociatedAttendeeCount": 1,
  "Custom1": null,
  "Custom2": null,
  "Custom3": null,
  "Custom4": null,
  "Custom5": null,
  "ID": "gWgSM$s2kvfcQ8xC$p6uaPsY6V6qB7FqOU",
  "URI": "https://www.concursolutions.com/api/v3.0/expense/entryattendeeassociations/gWgSM$s2kvfcQ8xC$p6uaPsY6V6qB7FqOU"
}

Create a New Entry-Attendee Association

POST /api/v3.0/expense/entryattendeeassociations

Parameters

Name Type Format Description
content - body Required The EntryAttendeeAssociation object to create.

Request URL

https://www.concursolutions.com/api/v3.0/expense/entryattendeeassociations

JSON Example of a Successful Response

{
  "ID": "gWgSM$s2kvfcQ8xC$p6uaPsY6V6qB7FqOU",
  "URI": "https://www.concursolutions.com/api/v3.0/expense/entryattendeeassociations/gWgSM$s2kvfcQ8xC$p6uaPsY6V6qB7FqOU"
}

Update a Specified Entry-Attendee Association

PUT /api/v3.0/expense/entryattendeeassociations/{id}

Parameters

Name Type Format Description
id string path Required The ID of the entry-attendee association.
content - body Required The partial or complete EntryAttendeeAssociation object to update.

Delete a Specified Entry-Attendee Association

DELETE /api/v3.0/expense/entryattendeeassociations/{id}

Request URL

https://www.concursolutions.com/api/v3.0/expense/entryattendeeassociations/gWgSM%24s2kvfcQ8xC%24p6uaPsY6V6qB7FqOU

JSON Example of a Successful Response

no content

Parameters

Name Type Format Description
id string path Required The connection request ID.

Schema

Entry Attendee Associations

Name Type Format Description
Items array Entry Attendee Association The result collection.
NextPage string - The URI of the next page of results, if any.

Entry Attendee Association

Name Type Format Description
Amount Decimal - The portion of the entry transaction amount assigned to this attendee.
AssociatedAttendeeCount Int32 - The count of additional attendees associated with this attendee. A count greater than 1 means there are unnamed attendees associated with this attendee.
AttendeeID string - The unique identifier of the associated attendee. To obtain the attendee ID value, use the GET /expense/attendees endpoint. The value of the ID element in the response is the attendee ID.
Custom1 through Custom5 string - The details from the Custom fields. These fields may not have data, depending on the configuration.
EntryID string - The unique identifier of the associated entry. To obtain the attendee ID value, use the GET /expense/entries endpoint. The value of the ID element in the response is the entry ID.
ID string - The unique identifier of the resource.
URI string - The URI to the resource.

Reports v3

Prior Versions

Retrieve reports owned by the user based on search criteria

GET  /api/v3.0/expense/reports

Parameters

Name Type Format Description
offset string query Starting page offset
limit Int32 query Number of records to return (default 25)
user string query Optional. The login ID of the report owner(s) to use when searching for reports. If the value is set to LoginID, reports for the report owner with this login ID value are returned. If the value is set to ALL, reports for all report owners are returned. If this parameter is not specified, reports for the OAuth Consumer are returned. The access token owner (OAuth Consumer) must have the Web Services Admin role to use this parameter.
approvalStatusCode string query The status code for the Approval Status. The values can include Concur Expense standard codes or custom codes. The Concur Expense standard code values are: A_AAFH - Report submission triggered an anomaly and fraud check; A_ACCO - Report is pending reviews; A_APPR - Report has been approved; A_EXTV - Report is pending external validation; A_FILE - Report has been submitted; A_NOTF - Report has not been submitted; A_PBDG - Report approval is pending Budget approval; A_PECO - Report approval is pending Cost object approval; A_PEND - Report is pending manager approval; A_PVAL - Report is pending prepayment validation; A_RESU - Report needs to be resubmitted; A_RHLD - Report submission is pending receipt images; A_TEXP - Report expired in approval queue. For custom codes, contact Concur Developer Support.
paymentStatusCode string query The payment status code for the report. The values can include Concur Expense standard codes or custom codes. The Concur Expense standard code values are: P_HOLD - Report payment is on hold; P_NOTP - Report has not been paid; P_PAID - Report has been paid; P_PAYC - Payment is confirmed. Some or all of the report expenses have been paid; P_PROC - Report is in process to be paid. For custom codes, contact Concur Developer Support.
currencyCode string query The 3-letter ISO 4217 currency code for the report currency. Example: USD.
paymentType string query The unique identifier for the payment type that is the payment type for at least one expense entry in the report. Use PaymentTypeID from Response of GET Expense Group Configurations V3 to obtain valid payment types.
reimbursementMethod string query The method the report owner will be reimbursed. VALUES: ADPPAYR - ADP Payroll; APCHECK - AP (Company Check); CNQRPAY - Expense Pay; PMTSERV - Other Payment Service. NOTE: PAY_PAL is NOT supported.
approverLoginID string query The login ID for the report approver that is the current approver assigned to the report.
expenseTypeCode string query The expense type code that is the expense type for at least one expense entry in the report. Use ExpenseTypeCode from Response of GET Expense Group Configurations V3.
attendeeTypeCode string query The report contains expense entries that have attendees of the specified type.
countryCode string query The report country. Maximum 2 characters. Format: The ISO 3166-1 alpha-2 country code. Example: United States is US.
batchID string query The unique identifier for a payment batch where there is at least one report payee within the report. Use the BatchID from Response of GET Payment Batch List.
vendorName string query The Vendor Description that is the vendor for at least one expense entry in the report.
hasVAT Boolean query Determines if the report has at least one expense entry with VAT details. Format: true or false.
hasImages Boolean query Determines if the report has at least one expense entry with an entry image or if there is a report image for this report. Format: true or false.
hasAttendees Boolean query Determines if the report has at least one expense entry with an attendee. Format: true or false.
hasBillableExpenses Boolean query The IsBillable flag for at least one expense entry in the report. Format: true or false.
isTestUser Boolean query The report owner is a test user using the report for testing purposes in a non-production environment. Format: true or false.
expenseGroupConfigID string query The unique identifier for the expense group configuration associated to the report's expense group. Use the ID from the Response of the Expense Group Configurations V3.
entryTransactionDateBefore DateTime query The entry transaction date for at least one expense entry in the report is before this date. Accepted Formats: yyyy-MM-dd or yyyy-MM-ddTHH:mm:ss.SSS
entryTransactionDateAfter DateTime query The entry transaction date for at least one expense entry in the report is after this date. Accepted Formats: yyyy-MM-dd or yyyy-MM-ddTHH:mm:ss.SSS
createDateBefore DateTime query The report create date is before this date. Accepted Formats: yyyy-MM-dd or yyyy-MM-ddTHH:mm:ss.SSS
createDateAfter DateTime query The report create date is after this date. Accepted Formats: yyyy-MM-dd or yyyy-MM-ddTHH:mm:ss.SSS
userDefinedDateBefore DateTime query The report user defined date is before this date. Accepted Formats: yyyy-MM-dd or yyyy-MM-ddTHH:mm:ss.SSS
userDefinedDateAfter DateTime query The report user defined date is after this date. Accepted Formats: yyyy-MM-dd or yyyy-MM-ddTHH:mm:ss.SSS
submitDateBefore DateTime query The report submit date is before this date. Format: Accepted Formats: yyyy-MM-dd or yyyy-MM-ddTHH:mm:ss.SSS
submitDateAfter DateTime query The report submit date is after this date. Format: Accepted Formats: yyyy-MM-dd or yyyy-MM-ddTHH:mm:ss.SSS
processingPaymentDateBefore DateTime query The report processing payment date is before this date. Accepted Formats: yyyy-MM-dd or yyyy-MM-ddTHH:mm:ss.SSS
processingPaymentDateAfter DateTime query The report processing payment date is after this date. Accepted Formats: yyyy-MM-dd or yyyy-MM-ddTHH:mm:ss.SSS
paidDateBefore DateTime query The report paid date is before this date. Accepted Formats: yyyy-MM-dd or yyyy-MM-ddTHH:mm:ss.SSS
paidDateAfter DateTime query The report paid date is after this date. Accepted Formats: yyyy-MM-dd or yyyy-MM-ddTHH:mm:ss.SSS
modifiedDateBefore DateTime query The report modified date is before this date. Accepted Formats: yyyy-MM-dd or yyyy-MM-ddTHH:mm:ss.SSS
modifiedDateAfter DateTime query The report modified date is after this date. Accepted Formats: yyyy-MM-dd or yyyy-MM-ddTHH:mm:ss.SSS

Request URL

https://www.concursolutions.com/api/v3.0/expense/reports?limit=15&user=ALL

JSON example of a successful response

{
  "Items": [
    {
      "Name": "Canadian Tax",
      "Total": 1900,
      "CurrencyCode": "CAD",
      "Country": "CA",
      "CountrySubdivision": "CA-BC",
      "CreateDate": "2013-09-02T19:05:57.687",
      "SubmitDate": "2013-09-02T19:18:35.537",
      "ProcessingPaymentDate": "2013-09-02T19:40:48.533",
      "PaidDate": "2013-09-02T19:46:01.57",
      "ReceiptsReceived": false,
      "UserDefinedDate": "2013-09-02T00:00:00",
      "LastComment": "",
      "OwnerLoginID": "CAtraveler@concurconnect2.com",
      "OwnerName": "Canadian Traveler",
      "ApproverLoginID": null,
      "ApproverName": null,
      "ApprovalStatusName": "Approved",
      "ApprovalStatusCode": "A_APPR",
      "PaymentStatusName": "Sent for Payment",
      "PaymentStatusCode": "P_PAID",
      "LastModifiedDate": "2013-09-02T19:46:01.98",
      "PersonalAmount": 0,
      "AmountDueEmployee": 1500,
      "AmountDueCompanyCard": 0,
      "TotalClaimedAmount": 1900,
      "TotalApprovedAmount": 1900,
      "LedgerName": "DEFAULT",
      "PolicyID": "gWmINGEAkQoamAzOARD9NEBtuv0ppnbJ4lQ",
      "EverSentBack": false,
      "HasException": false,
      "WorkflowActionUrl": "http://www.concursolutions.com/api/v3.0/expense/reports/report/gWpkOyRxJoH6lOiUHqNhW93UWxhOZZw/WorkFlowAction?limit=15&user=ALL",
      "OrgUnit1": null,
      "OrgUnit2": null,
      "OrgUnit3": null,
      "OrgUnit4": null,
      "OrgUnit5": null,
      "OrgUnit6": null,
      "Custom1": null,
      "Custom2": null,
      "Custom3": null,
      "Custom4": null,
      "Custom5": null,
      "Custom6": null,
      "Custom7": null,
      "Custom8": null,
      "Custom9": null,
      "Custom10": null,
      "Custom11": null,
      "Custom12": null,
      "Custom13": null,
      "Custom14": null,
      "Custom15": null,
      "Custom16": null,
      "Custom17": null,
      "Custom18": null,
      "Custom19": null,
      "Custom20": null,
      "ID": "F4F027007E814C1CA70E",
      "URI": "https://www.concursolutions.com/api/v3.0/expense/reports/F4F027007E814C1CA70E"
    }
  ]
}

Retrieve a report by ID

GET /api/v3.0/expense/reports/{id}

Parameters

Name Type Format Description
id string path Required Report ID
user string query LoginID of the report owner needs to be specified in the query parameter when searching for specific report using ReportID. If Bearer Access token used in the API call is equal to the Bearer access token of the owner of the report, user parameter can be omitted. Parameter equal to ALL (user=ALL) is not allowed when operating on a single resource (single ReportID).

Request URL

https://www.concursolutions.com/api/v3.0/expense/reports/39BD9F7C5C3F4986A6A5?user=jimadmin@concurconnect2.com

JSON example of a successful response

{
  "Name": "Test 02",
  "Total": 307.01,
  "CurrencyCode": "USD",
  "Country": "US",
  "CountrySubdivision": null,
  "CreateDate": "2016-04-04T23:33:08.21",
  "SubmitDate": null,
  "ProcessingPaymentDate": null,
  "PaidDate": null,
  "ReceiptsReceived": false,
  "UserDefinedDate": "2016-04-04T00:00:00",
  "LastComment": "",
  "OwnerLoginID": "jimadmin@concurconnect2.com",
  "OwnerName": "Jim Admin",
  "ApproverLoginID": null,
  "ApproverName": null,
  "ApprovalStatusName": "Not Submitted",
  "ApprovalStatusCode": "A_NOTF",
  "PaymentStatusName": "Not Paid",
  "PaymentStatusCode": "P_NOTP",
  "LastModifiedDate": "2016-04-23T02:53:23.7",
  "PersonalAmount": 0,
  "AmountDueEmployee": 290,
  "AmountDueCompanyCard": 0,
  "TotalClaimedAmount": 307.01,
  "TotalApprovedAmount": 307.01,
  "LedgerName": "DEFAULT",
  "PolicyID": "gWmINGEAkQoapyOLKfSdm0A9qK0ZVUvwolA",
  "EverSentBack": false,
  "HasException": true,
  "WorkflowActionUrl": "",
  "OrgUnit1": null,
  "OrgUnit2": null,
  "OrgUnit3": null,
  "OrgUnit4": null,
  "OrgUnit5": null,
  "OrgUnit6": null,
  "Custom1": null,
  "Custom2": null,
  "Custom3": null,
  "Custom4": null,
  "Custom5": null,
  "Custom6": null,
  "Custom7": null,
  "Custom8": null,
  "Custom9": null,
  "Custom10": null,
  "Custom11": null,
  "Custom12": null,
  "Custom13": null,
  "Custom14": null,
  "Custom15": null,
  "Custom16": null,
  "Custom17": null,
  "Custom18": null,
  "Custom19": null,
  "Custom20": null,
  "ID": "39BD9F7C5C3F4986A6A5",
  "URI": "http://www.concursolutions.com/api/v3.0/expense/reports/39BD9F7C5C3F4986A6A5"
}

Create a new report

Note: Expense reports will be created under the user's default expense policy. If a user has two expense policies - default and purchasing card - passing the PolicyKey on the post body will be ignored by Expense. That is, the expense report will always be under the default expense policy.

POST /api/v3.0/expense/reports

Parameters

Name Type Format Description
content - body Required Report object to create

Update a report

Request URL

https://www.concursolutions.com/api/v3.0/expense/reports

JSON example of a successful response

{
  "ID": "DD683A53018A4349B7CD",
  "URI": "https://www.concursolutions.com/api/v3.0/expense/reports/DD683A53018A4349B7CD"
}

PUT /api/v3.0/expense/reports/{id}

Parameters

Name Type Format Description
id string path Required The unique identifier for the report.
content body Required The report object to update

Schema

Reports

Name Type Format Description
Items array Report The result collection.
NextPage string - The URI of the next page of results, if any.

Report

Name Type Format Description
AmountDueCompanyCard Decimal - The total amount due to the company card for the report. Maximum 23 characters.
AmountDueEmployee Decimal - The total amount due to the employee for the report. Maximum 23 characters.
ApprovalStatusCode string - The approval status code for the report.
ApprovalStatusName string - The report's approval status, in the OAuth consumer's language.
ApproverLoginID string - The Login ID of the report owner's expense approver.
ApproverName string - The name of the report owner's expense approver.
Country string - The report country. Maximum 2 characters. Format: The ISO 3166-1 alpha-2 country code. Example: United States is US.
CountrySubdivision string - The report country subdivision. Format: ISO 3166-2:2007 country subdivision.
CreateDate DateTime - The date the report was created.
CurrencyCode string - The 3-letter ISO 4217 currency code for the expense report currency. Examples: USD - US dollars; BRL - Brazilian real; CAD - Canadian dollar; CHF - Swiss franc; EUR - Euro; GBO - Pound sterling; HKD - Hong Kong dollar; INR - Indian rupee; MXN - Mexican peso; NOK - Norwegian krone; SEK - Swedish krona.
Custom1 thorugh Custom20 CustomField - The details from the Custom fields. These may not have data, depending on configuration.
EverSentBack Boolean - Whether the report has ever been sent back to the employee. Format: Y/N
HasException Boolean - Whether the report has exceptions. Format: Y/N
ID string - The unique identifier of the resource.
LastComment string - The text of the most recent comment on the report.
LastModifiedDate DateTime - The date the report header was last modified.
LedgerName string - The name of the expense report ledger. Maximum 20 characters.
Name string - Required The name of the report.
OrgUnit1 through OrgUnit6 CustomField - The details from the Org Unit fields. These may not have data, depending on configuration.
OwnerLoginID string - The Login ID of the user this report belongs to.
OwnerName string - The name of the expense report owner.
PaidDate DateTime - The date when all journal entries in the report was integrated with or extracted to the financial system.
PaymentStatusCode string - The code for the payment status of the report.
PaymentStatusName string - The report's payment status, in the OAuth consumer's language.
PersonalAmount Decimal - The total amount of expenses marked as personal. Maximum 23 characters.
PolicyID string - The unique identifier of the policy that applies to this report. Maximum 64 characters. User's default expense policy is being used when creating a new expense report. Note: Policy cannot be changed via the v3 Reports API.
ProcessingPaymentDate DateTime - The date that the report completed all approvals and was ready to be extracted for payment.
ReceiptsReceived Boolean - If Y, then this entry has been marked as confirmed by the Expense Processor. Format: Y/N
SubmitDate DateTime - The date the report was submitted.
Total Decimal - The total amount of the report.
TotalApprovedAmount Decimal - The total amount of approved expenses in the report. Maximum 23 characters.
TotalClaimedAmount Decimal - The total amount of all non-personal expenses in the report. Maximum 23 characters.
URI string - The URI to the resource.
UserDefinedDate DateTime - The date of the report assigned by the user.
WorkflowActionUrl string - The URL to post a workflow action to the report using the Post Report Workflow Action function.

Custom Field

Name Type Format Description
Code string - For list fields, this is the list item code.
ListItemID string - For list fields, this is the list item ID.
Type string - The custom field type. Possible values: Amount, Boolean, ConnectedList, Date, Integer, List, Number, Text
Value string - The value in the Org Unit or Custom field. For list fields, this is the name of the list item. Maximum length: 48 characters

Request URL

https://www.concursolutions.com/api/v3.0/expense/reports/39BD9F7C5C3F4986A6A5

JSON example of a successful response

no content

Allocations v4

The Allocations API can be used to read the allocations that belong to a specific expense on an expense report and modify an allocation on an existing expense in an expense report. This API can be used to change custom field attributes, etc.

Limitations: This API is only available to partners who have been granted access by SAP Concur. Access to this documentation does not provide access to the API.

Prior Versions

Products and Editions

Scope Usage

Required Scopes:

Name Description Endpoint
expense.report.read Get information about expense reports. GET
expense.report.readwrite Read and write expense report headers. PATCH
user.read Get User Information, necessary for userID. GET

Optional Scope:

Name Description Endpoint
spend.listitem.read Read only access to spend list items listItemId. GET
spend.list.read Read only access to spend list and category details. GET

Dependencies

SAP Concur clients must purchase Concur Expense in order to use this API. This API requires the Identity v4 API which is currently only available to approved early access partners. Please contact your SAP Concur representative for more information.

Access Token Usage

This API supports both company level and user level access tokens.

Retrieve Allocations of an Expense ID on a Specific Report ID

Retrieves the allocations that belong to a specific expense ID on a specific report ID.

Scopes

expense.report.read - Refer to Scope Usage for full details.

Request

URI Template

https://{datacenterURI}/expensereports/v4/users/{userID}/context/{contextType}/reports/{reportId}/expenses/{expenseId}/allocations

Parameters

Name Type Format Description
userID string - Required The unique identifier of the SAP Concur user. Use Identity v4 API to retrieve the userID.
contextType string - Required The access level of the SAP Concur user, which determines the form fields they can view/modify. Supported value: TRAVELER
reportId string - Required The unique identifier of the report to which the expense entry belongs whose allocations are being retrieved.
expenseId string - Required The unique identifier of the expense entry whose allocations are being retrieved.

Headers

Response

Status Codes

Headers

Payload

Example

Request

curl --location --request GET 'https://us.api.concursolutions.com/expensereports/v4/users/32c2fcc3-b2e8-4907-9672-5b3f49b1c643/context/TRAVELER/reports/764428DD6A664AF0BFCB/expenses/29EE3C62F5D844458828A5C1086072D1/allocations' \
--header 'Authorization: Bearer {access_token}' \
--header 'Concur-CorrelationId: Expense-Allocation-test' \
--header 'Content-Type: application/json'

Response

200 OK

[
    {
        "customData": [
            {
                "id": "custom9",
                "value": "D3954B47BCEC9446A4FFC49E0000B46E",
                "isValid": true
            }
        ],
        "allocationId": "3BBB494511E1C74DA04469C45B039871",
        "accountCode": "Pending Client",
        "overLimitAccountCode": null,
        "allocationAmount": {
            "value": 250.00,
            "currencyCode": "USD"
        },
        "approvedAmount": {
            "value": 250.00,
            "currencyCode": "USD"
        },
        "claimedAmount": {
            "value": 250.00,
            "currencyCode": "USD"
        },
        "expenseId": "29EE3C62F5D844458828A5C1086072D1",
        "isSystemAllocation": false,
        "isPercentEdited": false,
        "percentage": 50.00000000
    },
    {
        "customData": [
            {
                "id": "custom9",
                "value": "88EACA3116581248BCE27956DE67647D",
                "isValid": true
            }
        ],
        "allocationId": "4DB06B4360E31443AD43ED52B2AE007E",
        "accountCode": "Pending Client",
        "overLimitAccountCode": null,
        "allocationAmount": {
            "value": 250.00,
            "currencyCode": "USD"
        },
        "approvedAmount": {
            "value": 250.00,
            "currencyCode": "USD"
        },
        "claimedAmount": {
            "value": 250.00,
            "currencyCode": "USD"
        },
        "expenseId": "29EE3C62F5D844458828A5C1086072D1",
        "isSystemAllocation": false,
        "isPercentEdited": false,
        "percentage": 50.00000000
    }
]

Retrieve an Allocation by ID

Retrieves the details of the specific allocation of an expense entry on a report.

Scopes

expense.report.read - Refer to Scope Usage for full details.

Request

URI Template

https://{datacenterURI}/expensereports/v4/users/{userID}/context/{contextType}/reports/{reportId}/allocations/{allocationId}

Parameters

Name Type Format Description
userID string - Required The unique identifier of the SAP Concur user. Use Identity v4 API to retrieve the userID.
contextType string - Required The access level of the SAP Concur user, which determines the form fields they can view/modify. Supported values: TRAVELER, PROXY
reportId string - Required The unique identifier of the report to which this allocation belongs.
allocationId string - Required The unique identifier of the allocation that is being retrieved.

Headers

Response

Status Codes

Headers

Payload

Example

Request

curl --location --request GET 'https://us.api.concursolutions.com/expensereports/v4/users/32c2fcc3-b2e8-4907-9672-5b3f49b1c643/context/TRAVELER/reports/764428DD6A664AF0BFCB/allocations/3BBB494511E1C74DA04469C45B039871' \
--header 'Authorization: Bearer {access_token}' \
--header 'Concur-CorrelationId: Expense-Allocation-test' \
--header 'Content-Type: application/json'

Response

200 OK

{
    "customData": [
        {
            "id": "custom9",
            "value": "D3954B47BCEC9446A4FFC49E0000B46E",
            "isValid": true
        }
    ],
    "allocationId": "3BBB494511E1C74DA04469C45B039871",
    "accountCode": "Pending Client",
    "overLimitAccountCode": null,
    "allocationAmount": {
        "value": 250.00,
        "currencyCode": "USD"
    },
    "approvedAmount": {
        "value": 250.00,
        "currencyCode": "USD"
    },
    "claimedAmount": {
        "value": 250.00,
        "currencyCode": "USD"
    },
    "expenseId": "29EE3C62F5D844458828A5C1086072D1",
    "isSystemAllocation": false,
    "isPercentEdited": false,
    "percentage": 50.00000000
}

Update a Specific Allocation

Updates the attributes of a specific allocation.

Scopes

expense.report.readwrite - Refer to Scope Usage for full details.

Request

URI Template

https://{datacenterURI}/expensereports/v4/users/{userID}/context/{contextType}/reports/{reportId}/allocations/{allocationId}

Parameters

Name Type Format Description
userID string - Required The unique identifier of the SAP Concur user. Use Identity v4 API to retrieve the userID.
contextType string - Required The access level of the SAP Concur user, which determines the form fields they can view/modify. Supported values: TRAVELER, PROXY
reportId string - Required The unique identifier of the report to which this allocation belongs.
allocationId string - Required The unique identifier of the allocation that is being retrieved.

Headers

REST Design Specification

PATCH operations in Expense Reports v4 conform to the JSON Merge Patch specification:

Payload

Response

Status Codes

Headers

Payload

Example

Request

curl --location --request PATCH 'https://us.api.concursolutions.com/expensereports/v4/users/32C2FCC3-B2E8-4907-9672-5B3F49B1C643/context/TRAVELER/reports/764428DD6A664AF0BFCB/allocations/3BBB494511E1C74DA04469C45B039871' \
--header 'Authorization: Bearer {access_token}' \
--header 'Concur-CorrelationId: Viswa test' \
--header 'Content-Type: application/json' \
--header 'Content-Type: text/plain' \
--data-raw '{
    "allocation":{
    "customData": [
        {
            "id": "custom9",
            "value": "058713001E2CD943824280D9275FDC3F",
            "isValid": true
        }
    ]
    },

    "expenseIds": ["29EE3C62F5D844458828A5C1086072D1"]

}'

Response

204 No Content

Schema

ReportAllocationResponse

Name Type Format Description
accountCode string - The ledger account code associated with the allocation.
allocationAmount Amount - The amount of the allocation.
allocationId string - Required The unique identifier of the allocation.
approvedAmount Amount - The pro-rated amount of the allocation approved for reimbursement based on the approved expense amount.
claimedAmount Amount - The amount of the allocation requested for reimbursement.
customData CustomData - The details from the customData fields. These fields may not have data, depending on the configuration.
expenseId string - Required The unique identifier of the expense associated with the allocation.
isPercentEdited boolean true/false Required Whether the allocation percent has been edited.
isSystemAllocation boolean true/false Required Whether the allocation is a system allocation, usually hidden from the user. If displayed to the user, should be read-only.
overLimitAccountCode string - The ledger account code associated with the allocation if it exceeds a pre-defined threshold, for example, the user’s travel allowance limit.
percentage number double Required The percentage of the total expense that this allocation represents.

CustomData

Name Type Format Description
id string - Required The unique identifier of the custom field. Examples: custom1, orgUnit1
isValid boolean true/false Whether the value returned is valid or not. This value is returned for custom fields of all data types and is specifically evaluated for list items to represent the current status. Default: true
value string - The value of the custom field. This field can have values for all the supported data types such as text, integer, boolean and listItemId. Maximum length: 48 characters

Amount

Name Type Format Description
currencyCode string - Required The 3-letter ISO 4217 currency code for the expense report currency, based on the user's assigned reimbursement currency when the report was created. Examples: USD - US dollars; BRL - Brazilian real; CAD - Canadian dollar; CHF - Swiss franc; EUR - Euro; GBO - Pound sterling; HKD - Hong Kong dollar; INR - Indian rupee; MXN - Mexican peso; NOK - Norwegian krone; SEK - Swedish krona
value number double Required The amount in the defined currency.

UpdateReportAllocation

Name Type Format Description
allocation UpdateAllocation - Required This is an allocation custom data object to be updated.
expenseIds string - Required This is an array of unique identifiers of expenses within this report that are being updated.

UpdateAllocation

Name Type Format Description
customData CustomData - The details from the customData fields. These fields may not have data, depending on the configuration.
Name Type Format Description
deprecation string - -
href string - Required The URL of the related HATEOAS link that you can use for subsequent calls.
hreflang string - -
isTemplated boolean true/false Required Whether the href is parameterized.
media string - -
method string - Required The HTTP method required for the related call.
rel string - Required The link relationship that describes how the href relates to the API call.
title string - -
type string - -

ErrorMessage

Name Type Format Description
errorId string - The unique identifier of the error associated with the response.
errorMessage string - Required The detailed error message.
httpStatus string - Required The http response code and phrase for the response.
path string - Required The URI of the attempted request.
timestamp string date-time Required The time when the error was captured.
validationErrors ValidationError - The validation error messages.

ValidationError

Name Type Format Description
id string - The ID of the validation error.
message string - The detailed message of the validation error.
source string - The type of validation which failed.

Comments v4

The Comments v4 API is used to read the comments entered on the expense report header, or expenses of an existing expense report. This API is used to detail information about spending that occurs out of policy, which is justified by the report owner, or inaccuracies pointed out by the approvers of the expense report.

Limitations: This API is only available to partners who have been granted access by SAP Concur. Access to this documentation does not provide access to the API.

Prior Versions

Products and Editions

Scope Usage

Required Scopes:

Name Description Endpoint
expense.report.read Get information about expense reports. GET
user.read Get User Information, necessary for userID. GET

Optional Scope:

Name Description Endpoint
expense.report.readwrite Read and write expense report headers. PATCH
expense.report.workflowstatus.write Approve or Send Back the Report in the workflow PATCH

Dependencies

SAP Concur clients must purchase Concur Expense in order to use this API. This API requires the Identity v4 API which is currently only available to approved early access partners. Please contact your SAP Concur representative for more information.

Access Token Usage

This API supports both company level and user level access tokens.

Retrieve Report Header Comments

Retrieves the comments on the specific report header.

Scopes

expense.report.read - Refer to Scope Usage for full details.

Request

URI Template

https://{datacenterURI}/expensereports/v4/users/{userID}/context/{contextType}/reports/{reportId}/comments

Parameters

Name Type Format Description
userID string - Required The unique identifier of the SAP Concur user. Use Identity v4 to retrieve the userID.
contextType string - Required The access level of the SAP Concur user, which determines the form fields they can view/modify. Supported values: TRAVELER, PROXY
reportId string - Required The unique identifier of the report that is being read.

Headers

Response

Status Codes

Headers

Payload

Example

Request

curl --location --request GET 'https://us.api.concursolutions.com/expensereports/v4/users/32C2FCC3-B2E8-4907-9672-5B3F49B1C643/context/TRAVELER/reports/764428DD6A664AF0BFCB/comments' \
--header 'Authorization: Bearer {access_token}' \
--header 'Concur-CorrelationId: Expense-Report-test' \
--header 'Content-Type: application/json'

Response

200 OK

[
  {
    "comment": "This is an expense report for office supplies",
    "creationDate": "2021-03-17T22:29:50.090Z",
    "author": {
      "firstName": "Concur",
      "lastName": "Administrator",
      "middleInitial": ""
    },
    "createdForEmployeeId": "32c2fcc3-b2e8-4907-9672-5b3f49b1c643",
    "createdForEmployee": {
      "firstName": "Tester",
      "lastName": "Insert",
      "middleInitial": "A"
    },
    "isLatest": true
  }
]

Retrieve Expense Comments

Retrieves the comments on the specific expense within an expense report.

Scopes

expense.report.read - Refer to Scope Usage for full details.

Request

URI Template

https://{datacenterURI}/expensereports/v4/users/{userID}/context/{contextType}/reports/{reportId}/expenses/{expenseId}/comments

Parameters

Name Type Format Description
userID string - Required The unique identifier of the SAP Concur user. Use Identity v4 to retrieve the userID.
contextType string - Required The access level of the SAP Concur user, which determines the form fields they can view/modify. Supported values: TRAVELER, PROXY
reportId string - Required The unique identifier of the report to which this expense entry belongs.
expenseId string - Required The unique identifier of the expense entry to which the comments belong.

Headers

Response

Status Codes

Headers

Payload

Example

Request

curl --location --request GET 'https://us.api.concursolutions.com/expensereports/v4/users/32C2FCC3-B2E8-4907-9672-5B3F49B1C643/context/TRAVELER/reports/764428DD6A664AF0BFCB/expenses/84FCBB92BD4E5342B849DAC29FD163A1/comments' \
--header 'Authorization: Bearer {access_token}' \
--header 'Concur-CorrelationId: Expense-Report-test' \
--header 'Content-Type: application/json'

Expense Comments Response

200 OK

[
    {
        "comment": "This expense is allowed due to the pandemic",
        "creationDate": "2021-03-17T23:05:40.340Z",
        "author": {
            "firstName": "Concur",
            "lastName": "Administrator",
            "middleInitial": ""
        },
        "createdForEmployeeId": "32c2fcc3-b2e8-4907-9672-5b3f49b1c643",
        "createdForEmployee": {
            "firstName": "Tester",
            "lastName": "Insert",
            "middleInitial": "A"
        },
        "isLatest": true
    }
]

Schema

Report Header Comments

Name Type Format Description
commentDetails array commentDetails A key linking to another schema for the format.

Expense Comments

Name Type Format Description
commentDetails array commentDetails A key linking to another schema for the format.

commentDetails

Name Type Format Description
author Employee - Required The comment author's name.
comment string - Required The comments input on the report by all users.
createdForEmployee Employee - Required The name of the employee the comment was created on behalf of. This would differ from the comment author only in the case of delegates creating the comment.
createdForEmployeeId string - Required The unique identifier of the employee the comment was created on behalf of. This would differ from the comment author only in the case of delegates creating the comment.
creationDate string YYYY-MM-DDTHH:mm:ssZ.SSS'Z' Required The UTC datetime when the comment was created on the report or expense.
isLatest boolean true/false Required If true, this attribute represents the latest comment by the user.

Employee

Name Type Format Description
firstName string - First name of the employee.
lastName string - Last name of the employee.
middleInitial string - Middle initial of the employee.

Error Message

Name Type Format Description
errorId string - The unique identifier of the error associated with the response.
errorMessage string - Required The detailed error message.
httpStatus string - Required The http response code and phrase for the response.
path string - Required The URI of the attempted request.
timestamp string date-time Required The time when the error was captured.
validationErrors ValidationError - The validation error messages.

Validation Error

Name Type Format Description
id string - The ID of the validation error.
message string - The detailed message of the validation error.
source string - The type of validation which failed.

Expenses v4

The Expenses API can be used to read the expenses that belong to a specific expense report and modify an expense on an existing expense report. This API can be used to change attributes like transaction date, transaction amount, location, etc.

Limitations: This API is only available to partners who have been granted access by SAP Concur. Access to this documentation does not provide access to the API.

Prior Versions

Products and Editions

Scope Usage

Required Scopes:

Name Description Endpoint
expense.report.read Get information about expense reports. GET
expense.report.readwrite Read and write expense report headers. PATCH
user.read Get User Information, necessary for userID. GET

Optional Scope:

Name Description Endpoint
spend.listitem.read Read only access to spend list items listItemId. GET
spend.list.read Read only access to spend list and category details. GET

Dependencies

SAP Concur clients must purchase Concur Expense in order to use this API. This API requires the Identity v4 API which is currently only available to approved early access partners. Please contact your SAP Concur representative for more information.

Access Token Usage

This API supports both company level and user level access tokens.

Retrieve Expenses on a Specific Report ID

Retrieves the expenses that belong to a specific report ID.

Scopes

expense.report.read - Refer to Scope Usage for full details.

Request

URI Template

https://{datacenterURI}/expensereports/v4/users/{userID}/context/{contextType}/reports/{reportId}/expenses

Parameters

Name Type Format Description
userID string - Required The unique identifier of the SAP Concur user. Use Identity v4 API to retrieve the userID.
contextType string - Required The access level of the SAP Concur user, which determines the form fields they can view/modify. Supported value: TRAVELER
reportId string - Required The unique identifier of the report that is being read.

Headers

Response

Status Codes

Headers

Payload

Example

Request

curl --location --request GET 'https://us.api.concursolutions.com/expensereports/v4/users/32C2FCC3-B2E8-4907-9672-5B3F49B1C643/context/TRAVELER/reports/764428DD6A664AF0BFCB/expenses' \
--header 'Authorization: Bearer {access_token}' \
--header 'Concur-CorrelationId: Expense-Report-test' \
--header 'Content-Type: application/json'

Response

200 OK

[
    {
        "expenseId": "84FCBB92BD4E5342B849DAC29FD163A1",
        "approverAdjustedAmount": {
            "value": 25.00000000,
            "currencyCode": "USD"
        },
        "allocationState": "NOT_ALLOCATED",
        "allocationSetId": null,
        "approvedAmount": {
            "value": 25.00000000,
            "currencyCode": "USD"
        },
        "businessPurpose": "test",
        "claimedAmount": {
            "value": 25.00000000,
            "currencyCode": "USD"
        },
        "ereceiptImageId": null,
        "exchangeRate": {
            "value": 1.00000000000000,
            "operation": "MULTIPLY"
        },
        "expenseSourceIdentifiers": null,
        "expenseType": {
            "id": "LUNCH",
            "name": "Lunch",
            "code": "OTHER",
            "isDeleted": false
        },
        "hasBlockingExceptions": false,
        "hasExceptions": false,
        "hasMissingReceiptDeclaration": false,
        "isAutoCreated": false,
        "imageCertificationStatus": null,
        "isImageRequired": true,
        "isPaperReceiptRequired": false,
        "isPersonalExpense": false,
        "location": {
            "id": "04F3ED00D0884F4681628E3337A5B515",
            "name": "Bellevue, Washington",
            "city": "Bellevue",
            "countrySubDivisionCode": "US-WA",
            "countryCode": "US"
        },
        "paymentType": {
            "id": "CASH",
            "name": "Cash",
            "code": "CASH"
        },
        "postedAmount": {
            "value": 25.00000000,
            "currencyCode": "USD"
        },
        "receiptImageId": null,
        "ticketNumber": null,
        "transactionAmount": {
            "value": 25.00000000,
            "currencyCode": "USD"
        },
        "transactionDate": "2020-03-11",
        "travelAllowance": {
            "dailyLimitAmount": null,
            "dailyTravelAllowanceId": null,
            "isExpensePartOfTravelAllowance": false
        },
        "vendor": null,
        "attendeeCount": 1,
        "links": [
            {
                "rel": "self",
                "href": "https://us.api.concursolutions.com/expensereports/v4/users/32c2fcc3-b2e8-4907-9672-5b3f49b1c643/context/TRAVELER/reports/764428DD6A664AF0BFCB/expenses/84FCBB92BD4E5342B849DAC29FD163A1",
                "hreflang": null,
                "media": null,
                "title": null,
                "type": null,
                "deprecation": null,
                "method": "GET",
                "isTemplated": false
            }
        ]
    },
    {
        "expenseId": "29EE3C62F5D844458828A5C1086072D1",
        "approverAdjustedAmount": {
            "value": 500.00000000,
            "currencyCode": "USD"
        },
        "allocationState": "NOT_ALLOCATED",
        "allocationSetId": null,
        "approvedAmount": {
            "value": 500.00000000,
            "currencyCode": "USD"
        },
        "businessPurpose": "Facility supplies",
        "claimedAmount": {
            "value": 500.00000000,
            "currencyCode": "USD"
        },
        "ereceiptImageId": null,
        "exchangeRate": {
            "value": 1.00000000000000,
            "operation": "MULTIPLY"
        },
        "expenseSourceIdentifiers": null,
        "expenseType": {
            "id": "OFCSP",
            "name": "Office Supplies",
            "code": "OTHER",
            "isDeleted": false
        },
        "hasBlockingExceptions": false,
        "hasExceptions": false,
        "hasMissingReceiptDeclaration": false,
        "isAutoCreated": false,
        "imageCertificationStatus": null,
        "isImageRequired": true,
        "isPaperReceiptRequired": false,
        "isPersonalExpense": false,
        "location": {
            "id": "0BC6B782B77349898E2CA814F5B57C08",
            "name": "Seattle, Washington",
            "city": "Seattle",
            "countrySubDivisionCode": "US-WA",
            "countryCode": "US"
        },
        "paymentType": {
            "id": "1022",
            "name": "Mastercard",
            "code": "CBCP"
        },
        "postedAmount": {
            "value": 500.00000000,
            "currencyCode": "USD"
        },
        "receiptImageId": null,
        "ticketNumber": null,
        "transactionAmount": {
            "value": 500.00000000,
            "currencyCode": "USD"
        },
        "transactionDate": "2020-03-11",
        "travelAllowance": {
            "dailyLimitAmount": null,
            "dailyTravelAllowanceId": null,
            "isExpensePartOfTravelAllowance": false
        },
        "vendor": {
            "id": null,
            "name": null,
            "description": "Antioch Construction"
        },
        "attendeeCount": 0,
        "links": [
            {
                "rel": "self",
                "href": "https://us.api.concursolutions.com/expensereports/v4/users/32c2fcc3-b2e8-4907-9672-5b3f49b1c643/context/TRAVELER/reports/764428DD6A664AF0BFCB/expenses/29EE3C62F5D844458828A5C1086072D1",
                "hreflang": null,
                "media": null,
                "title": null,
                "type": null,
                "deprecation": null,
                "method": "GET",
                "isTemplated": false
            }
        ]
    }
]

Retrieve an Expense by ID

Retrieves the details of the specific expense entry on a report.

Scopes

expense.report.read - Refer to Scope Usage for full details.

Request

URI Template

https://{datacenterURI}/expensereports/v4/users/{userID}/context/{contextType}/reports/{reportId}/expenses/{expenseId}

Parameters

Name Type Format Description
userID string - Required The unique identifier of the SAP Concur user. Use Identity v4 API to retrieve the userID.
contextType string - Required The access level of the SAP Concur user, which determines the form fields they can view/modify. Supported value: TRAVELER, PROXY
reportId string - Required The unique identifier of the report to which this expense entry belongs.
expenseId string - Required The unique identifier of the expense entry that is being read.

Headers

Response

Status Codes

Headers

Payload

Example

Request

curl --location --request GET 'https://us.api.concursolutions.com/expensereports/v4/users/32C2FCC3-B2E8-4907-9672-5B3F49B1C643/context/TRAVELER/reports/764428DD6A664AF0BFCB/expenses/84FCBB92BD4E5342B849DAC29FD163A1' \
--header 'Authorization: Bearer {access_token}' \
--header 'Concur-CorrelationId: Expense-Report-test' \
--header 'Content-Type: application/json'

Response

200 OK

{
    "expenseId": "84FCBB92BD4E5342B849DAC29FD163A1",
    "approverAdjustedAmount": {
        "value": 25.00000000,
        "currencyCode": "USD"
    },
    "allocationState": "NOT_ALLOCATED",
    "allocationSetId": null,
    "approvedAmount": {
        "value": 25.00000000,
        "currencyCode": "USD"
    },
    "businessPurpose": "test",
    "claimedAmount": {
        "value": 25.00000000,
        "currencyCode": "USD"
    },
    "ereceiptImageId": null,
    "exchangeRate": {
        "value": 1.00000000000000,
        "operation": "MULTIPLY"
    },
    "expenseSourceIdentifiers": null,
    "expenseType": {
        "id": "ONLIN",
        "name": "Online Fees",
        "code": "OTHER",
        "isDeleted": false
    },
    "hasBlockingExceptions": false,
    "hasExceptions": false,
    "hasMissingReceiptDeclaration": false,
    "isAutoCreated": false,
    "imageCertificationStatus": null,
    "isImageRequired": true,
    "isPaperReceiptRequired": false,
    "isPersonalExpense": false,
    "location": {
        "id": "04F3ED00D0884F4681628E3337A5B515",
        "name": "Bellevue, Washington",
        "city": "Bellevue",
        "countrySubDivisionCode": "US-WA",
        "countryCode": "US"
    },
    "paymentType": {
        "id": "CASH",
        "name": "Cash",
        "code": "CASH"
    },
    "postedAmount": {
        "value": 25.00000000,
        "currencyCode": "USD"
    },
    "receiptImageId": null,
    "ticketNumber": null,
    "transactionAmount": {
        "value": 25.00000000,
        "currencyCode": "USD"
    },
    "transactionDate": "2020-03-11",
    "travelAllowance": {
        "dailyLimitAmount": null,
        "dailyTravelAllowanceId": null,
        "isExpensePartOfTravelAllowance": false
    },
    "vendor": null,
    "attendeeCount": 1,
    "links": [
        {
            "rel": "self",
            "href": "https://us.api.concursolutions.com/expensereports/v4/users/32c2fcc3-b2e8-4907-9672-5b3f49b1c643/context/TRAVELER/reports/764428DD6A664AF0BFCB/expenses/84FCBB92BD4E5342B849DAC29FD163A1",
            "hreflang": null,
            "media": null,
            "title": null,
            "type": null,
            "deprecation": null,
            "method": "GET",
            "isTemplated": false
        }
    ],
    "budgetAccrualDate": null,
    "authorizationRequestExpenseId": null,
    "customData": [
        {
            "id": "custom9",
            "value": "AB8596D91C994F4DBBD820D6DCBDC599",
            "isValid": true,
            "listItemUrl": "https://us.api.concursolutions.com/list/v4/items?id=AB8596D91C994F4DBBD820D6DCBDC599"
        }
    ],
    "expenseTaxSummary": {
        "totalTaxPostedAmount": {
            "value": 0E-8,
            "currencyCode": "USD"
        },
        "totalTaxAdjustedAmount": {
            "value": 0E-8,
            "currencyCode": "USD"
        },
        "totalReclaimPostedAmount": {
            "value": 0E-8,
            "currencyCode": "USD"
        },
        "totalReclaimAdjustedAmount": {
            "value": 0E-8,
            "currencyCode": "USD"
        },
        "netTaxAmount": {
            "value": 25.00000000,
            "currencyCode": "USD"
        },
        "netAdjustedTaxAmount": {
            "value": 25.00000000,
            "currencyCode": "USD"
        },
        "netReclaimAmount": {
            "value": 25.00000000,
            "currencyCode": "USD"
        },
        "netReclaimAdjustedAmount": {
            "value": 25.00000000,
            "currencyCode": "USD"
        },
        "vatTaxTotal": null
    },
    "isExcludedFromCashAdvanceByUser": false,
    "isExpenseBillable": false,
    "isExpenseRejected": false,
    "isPaperReceiptReceived": false,
    "merchantTaxId": null,
    "mileage": null,
    "parentExpenseId": null,
    "receiptType": {
        "id": "N",
        "status": "No Receipt"
    },
    "taxRateLocation": "HOME",
    "travel": null,
}

Update a Specific Expense Entry in an Unsubmitted Report

Updates the specified expense in an unsubmitted report and is flexible for modifying multiple attributes in the schema detailed below

Scopes

expense.report.readwrite - Refer to Scope Usage for full details.

Request

URI Template

https://{datacenterURI}/expensereports/v4/users/{userID}/context/{contextType}/reports/{reportId}/expenses/{expenseId}

Parameters

Name Type Format Description
userID string - Required The unique identifier of the SAP Concur user. Use Identity v4 API to retrieve the userID.
contextType string - Required The access level of the SAP Concur user, which determines the form fields they can view/modify. Supported value: TRAVELER, PROXY
reportId string - Required The unique identifier of the report to which this expense entry belongs.
expenseId string - Required The unique identifier of the expense entry that is being read.

Headers

REST Design Specification

PATCH operations in Expense Reports v4 conform to the JSON Merge Patch specification:

Payload

Response

Status Codes

Headers

Payload

Example

Request

curl --location --request PATCH 'https://us.api.concursolutions.com/expensereports/v4/users/32C2FCC3-B2E8-4907-9672-5B3F49B1C643/context/TRAVELER/reports/764428DD6A664AF0BFCB/expenses/84FCBB92BD4E5342B849DAC29FD163A1' \
--header 'Authorization: Bearer {access_token}' \
--header 'Concur-CorrelationId: Expense-Test' \
--header 'Content-Type: application/json' \
--header 'Content-Type: text/plain' \
--data-raw '{
    "customData": [
        {
            "id": "custom09",
            "value": "81188b39-605d-2d4f-b80b-43efa84a7b49",
            "isValid": true
        }
    ],
    "businessPurpose":"Office Facility Supplies",
    "transactionAmount":{
        "value": 50.00000000,
        "currencyCode": "USD"
    },
    "expenseSource":"OTHER"
}'

Response

204 No Content

Update a Specific Expense Entry in a Submitted Report

Updates the specified expense in an unsubmitted or submitted report and is restricted to modify 'Business Purpose' and 'Custom/Org unit' fields only.

Scopes

expense.report.readwrite - Refer to Scope Usage for full details.

Request

URI Template

https://{datacenterURI}/expensereports/v4/reports/{reportId}/expenses/{expenseId}

Parameters

Name Type Format Description
reportId string - Required The unique identifier of the report to which this expense entry belongs.
expenseId string - Required The unique identifier of the expense entry that is being read.

Headers

REST Design Specification

PATCH operations in Expense Reports v4 conform to the JSON Merge Patch specification:

Payload

Response

Status Codes

Headers

Payload

Update Report Expense Compact Schema

Name Type Format Description
businessPurpose string - The text input for the business purpose by the user. Maximum length: 64 characters
customData CustomData - The details from the customData fields. These fields may not have data, depending on the configuration.
expenseSource string - Required The source of the expense. Supported values: EA - Expense Assistant, MOB - Mobile, OTHER - Unknown, SE - Smart Expense, TA - Travel Allowance, TR - Travel Request, UI - Web UI

CustomData

Name Type Format Description
id string - Required The unique identifier of the custom field. Examples: custom1, orgUnit1
isValid boolean true/false Whether the value returned is valid or not. This value is returned for custom fields of all data types and is specifically evaluated for list items to represent the current status. Default: true
value string - The value of the custom field. This field can have values for all the supported data types such as text, integer, boolean and listItemId. Maximum length: 48 characters

Example

Request

curl --location --request PATCH 'https://us.api.concursolutions.com/expensereports/v4/reports/764428DD6A664AF0BFCB/expenses/84FCBB92BD4E5342B849DAC29FD163A1' \
--header 'Authorization: Bearer {access_token}' \
--header 'Concur-CorrelationId: Expense-Test' \
--header 'Content-Type: application/json' \
--header 'Content-Type: text/plain' \
--data-raw '{
    "customData": [
        {
            "id": "custom09",
            "value": "81188b39-605d-2d4f-b80b-43efa84a7b49",
            "isValid": true
        }
    ],
    "businessPurpose":"Office Supplies",
    "expenseSource":"OTHER"
}'

Response

204 No Content

Schema

ReportExpenseSummary

Name Type Format Description
allocationSetId string - The identifier of the allocation set associated with the expense. Allocations which belong to the same set were created at the same time.
allocationState string - Required Allocation state for the expense. Supported values: FULLY_ALLOCATED, NOT_ALLOCATED, PARTIALLY_ALLOCATED
approvedAmount Amount - The approved amount of the expense, in the report currency.
approverAdjustedAmount Amount - The total amount adjusted for the expense by the approver
attendeeCount integer int32 The total number of attendees associated with the expense.
businessPurpose string - The text input for the business purpose by the user.
claimedAmount Amount - The total non-personal amount claimed for reimbursement for the expense.
ereceiptImageId string - The unique identifier of the eReceipt image associated with the expense.
exchangeRate ExchangeRate - Required Exchange rate data for the expense.
expenseId string - Required The unique identifier for the expense.
expenseSourceIdentifiers ExpenseSourceIdentifiers - The list of expense sources associated with the expense
expenseType ExpenseType - Required The expense type information for the expense.
hasBlockingExceptions boolean - Required Whether the expense has any exceptions that block it from being submitted.
hasExceptions boolean true/false Required Whether the expense has any exceptions.
hasMissingReceiptDeclaration boolean true/false Required Whether the expense has an affidavit declaration for missing receipt.
imageCertificationStatus string - The final status of the receipt image associated with the expense.
isAutoCreated boolean true/false Required Whether the expense is auto-created.
isImageRequired boolean true/false Required Whether the image is required for the expense.
isPaperReceiptRequired boolean true/false Required Whether the paper receipt is required for the expense to be submitted.
isPersonalExpense boolean true/false Required Whether the expense is marked as personal (non-reimbursable) by the user.
jptRouteId string - The unique route ID to identify a Japan rail route.
links Link - Resource links related to this call.
location Location - The location information of the expense.
paymentType PaymentType - Required The payment type information for the expense.
postedAmount Amount - Required The amount of the expense, in the report currency.
receiptImageId string - The unique identifier of the image associated with the expense.
ticketNumber string - The ticket number associated with the travel.
transactionAmount Amount - Required The amount of the expense, in the transaction currency paid to the vendor.
transactionDate string YYYY-MM-DD The transaction date.
travelAllowance TravelAllowance - The travel allowance data associated with the expense.
vendor Vendor - The vendor information for the expense.

ReportExpenseDetail

Name Type Format Description
allocationSetId string - The identifier of the allocation set associated with the expense. Allocations which belong to the same set are created at the same time.
allocationState string - Required Allocation state for the expense. Supported values: FULLY_ALLOCATED, NOT_ALLOCATED, PARTIALLY_ALLOCATED
approvedAmount Amount - The approved amount of the expense, in the report currency.
approverAdjustedAmount Amount - The total amount adjusted for the expense by the approver.
attendeeCount integer int32 The total number of attendees associated with the expense.
authorizationRequestExpenseId string - The authorization request expense ID associated with the expense.
budgetAccrualDate string YYYY-MM-DD The budget accrual date of the expense.
businessPurpose string - The text input for the business purpose by the user.
claimedAmount Amount - The total non-personal amount claimed for reimbursement for the expense
customData CustomData - The details from the customData fields. These fields may not have data, depending on the configuration.
ereceiptImageId string - The unique identifier of the eReceipt image associated with the expense.
exchangeRate ExchangeRate - Required Exchange rate data for the expense.
expenseId string - Required The unique identifier for the expense
expenseSourceIdentifiers ExpenseSourceIdentifiers - The list of expense sources associated with the expense.
expenseTaxSummary ExpenseTaxSummary - Tax information for the expense.
expenseType ExpenseType - Required The expense type information for the expense.
hasBlockingExceptions boolean true/false Required Whether the expense has any exceptions that blocks it from being submitted.
hasExceptions boolean true/false Required Whether the expense has any exceptions.
hasMissingReceiptDeclaration boolean true/false Whether the expense has an affidavit declaration for missing receipt.
imageCertificationStatus string - The final status of the receipt image associated with the expense. Supported values: ACCEPTED, PROCESSED, PROCESSING, PDF, FAILED, NO_PROCESSING_REQUIRED
isAutoCreated boolean true/false Required Whether the expense is auto created.
isExcludedFromCashAdvanceByUser boolean true/false Required Whether the user has excluded the expense from cash advance.
isExpenseBillable boolean true/false Required Whether the expense is billable.
isExpenseRejected boolean true/false Required Whether the approver or processor has rejected this expense in the report. If true, then this expense will be sent back to the report submitted in an addendum (split) report.
isImageRequired boolean true/false Required Whether the image is required for the expense.
isPaperReceiptReceived boolean true/false Required Whether the paper receipt was received for the expense.
isPaperReceiptRequired boolean true/false Required Whether the paper receipt is required for the expense to be submitted.
isPersonalExpense boolean true/false Required Whether the expense is marked as personal (non-reimbursable) by the user.
jptRouteId string - The unique route ID to identify a Japan rail route.
links Link - Resource links related to this call.
location Location - The location information of the expense.
merchantTaxId string - Merchant tax ID for the expense.
mileage Mileage - The mileage data associated with the expense.
parentExpenseId string - Expense ID of the parent expense.
paymentType PaymentType - Required The payment type information for the expense.
postedAmount Amount - Required The amount of the expense, in the report currency.
receiptImageId string - The unique identifier of the image associated with the expense.
receiptType ReceiptType - Receipt type for the expense.
taxRateLocation string - Required Transaction location relative to the employee's home location as defined by their user profile. Supported values: FOREIGN - The expense transaction took place in foreign currency, HOME - The expense transaction took place in the reimbursement currency, OUT_OF_PROVINCE - The expense transaction took place outside the state jurisdiction. Default: HOME
transactionAmount Amount - Required The amount of the expense, in the transaction currency paid to the vendor.
transactionDate string YYYY-MM-DD The transaction date of the expense.
travel Travel - The travel data associated with the expense.
travelAllowance TravelAllowance - The travel allowance data associated with the expense.
vendor Vendor - The vendor information for the expense.

CustomData

Name Type Format Description
id string - Required The unique identifier of the custom field. Examples: custom1, orgUnit1
isValid boolean true/false Whether the value returned is valid or not. This value is returned for custom fields of all data types and is specifically evaluated for list items to represent the current status. Default: true
value string - The value of the custom field. This field can have values for all the supported data types such as text, integer, boolean and listItemId. Maximum length: 48 characters

Amount

Name Type Format Description
currencyCode string - Required The 3-letter ISO 4217 currency code for the expense report currency, based on the user's assigned reimbursement currency when the report was created. Examples: USD - US dollars; BRL - Brazilian real; CAD - Canadian dollar; CHF - Swiss franc; EUR - Euro; GBO - Pound sterling; HKD - Hong Kong dollar; INR - Indian rupee; MXN - Mexican peso; NOK - Norwegian krone; SEK - Swedish krona
value number double Required The amount in the defined currency.

ExpenseSourceIdentifiers

Name Type Format Description
creditCardTransactionId string - The unique identifier of the credit card transaction (indexed transactionId) associated with the expense.
ereceiptId string - -
expenseCaptureImageId string - The unique identifier of the expense capture image associated with the expense.
jptRouteId string - The unique identifier to identify a Japan rail route.
personalCardTransactionId string - The unique identifier of the personal card transaction associated with the expense.
quickExpenseId string - The unique identifier of the mobile expense associated with the expense.
segmentId integer int64 The unique identifier of the segment associated with the expense.
segmentTypeId string - Segment type ID associated with the trip. Supported values: AIRFR - Air Ticket, AIRSU - Air Subscription, CARRT - Car Rental, DININ - Dining, EVENT - Event, HOTEL - Hotel Reservation, INSUR - Insurance, LIMOF - Limousine Reservation, MISC - Miscellaneous, PARKG - Parking Fee, RAILF - Train Ticket, RAISU - Train Subscription, TAXIF - Taxi Fare, VISA - Visa
tripId integer int64 The unique identifier of the trip ID associated with the expense.

ExchangeRate

Name Type Format Description
operation string - Required Exchange rate operation. Supported values: MULTIPLY or DIVIDE
value number double Required Exchange rate value.

ExpenseTaxSummary

Name Type Format Description
netAdjustedTaxAmount Amount - Net adjusted tax amount.
netReclaimAdjustedAmount Amount - Net reclaim adjusted amount.
netReclaimAmount Amount - Net reclaim amount.
netTaxAmount Amount - Net tax amount.
totalReclaimAdjustedAmount Amount - Total reclaim adjusted amount.
totalReclaimPostedAmount Amount - Total reclaim posted amount.
totalTaxAdjustedAmount Amount - Total tax adjusted amount.
totalTaxPostedAmount Amount - Total tax posted amount.
vatTaxTotal Amount - VAT tax total amount.

ExpenseType

Name Type Format Description
code string - The code of the expense type.
id string - Required The unique identifier of the expense type. Maximum length: 5 characters. Example: BRKFT
isDeleted boolean true/false Whether the expense type returned is deleted or not.
name string - The name of the expense type (localized as per accept-language header).

Location

Name Type Format Description
city string - The location city.
countryCode string - The location country ISO 3166-1 code.
countrySubDivisionCode string - The location country sub division ISO 3166-2 code.
id string - The unique identifier of the location. When location id is specified (when creating or updating a resource), other location object fields will be ignored.
name string - The location name (localized as per accept-language header).

Mileage

Name Type Format Description
hasCaravanAttached boolean true/false Whether the mileage expense has caravan or trailer attached to the car. Default: false
hasDogIncluded boolean true/false Whether the mileage expense includes a dog for work purposes. Default: false
hasForestOrConstructionSiteRoadInRoute boolean true/false Whether the mileage route is via a forest road or construction site road. Default: false
hasForestRoadInRoute boolean true/false Whether the mileage route has forest road. Default: false
hasMachinery boolean true/false Whether machines or equipment are transported in the car for this mileage expenses. Default: false
hasMobileCanteenOrHeavyLoadAttached boolean true/false Whether the mileage expense has mobile canteen or is transporting a heavy load attached to the car. Default: false
hasTrailerAttached boolean true/false Whether the mileage expense has trailer attached to the car. Default: false
isMarkedAsHigherRate boolean true/false Whether a higher rate should be applied to the mileage expense. Default: false
odometerEnd integer int32 The odometer reading at the end of the journey.
odometerStart integer int32 The odometer reading at the start of the journey.
passengerCount integer int32 The number of passengers in the vehicle during the journey.
personalDistance integer int32 The portion of the journey attributed to personal use. Default: 0
routeId string - The unique identifier of the route for this journey.
totalDistance integer int32 Required The total distance for this journey.
vehicleId string - Required The unique identifier for the vehicle used for this journey.

PaymentType

Name Type Format Description
code string - The code of the payment type.
id string - Required The unique identifier of the payment type. Maximum length: 4 characters. Example: CASH
name string - The name of the payment type (localized as per accept-language header).

ReceiptType

Name Type Format Description
id string - Required The unique identifier for the receipt type. Supported values: N - No Receipt, R - Regular Receipt, T - Tax Receipt. Default value: N
status string - Receipt status (localized as per accept-language header).

Travel

Name Type Format Description
airlineFeeTypeCode string - Airline fee type code. Supported values: BAGGS, BUSIN, OBENT, ONBRD, OTHER, PRACC, SEATS, TKCHG, UPGRD
airlineFeeTypeName string - The localized airline fee type name.
airlineServiceClassCode string - The airline service class code. Supported values: BUSIN, COACH, FIRST
airlineServiceClassName string - The localized airline service class name.
carRentalDays integer int32 The number of days car was rented. Minimum value: 0
endLocation string - Location where the travel ended. Maximum length: 100 characters
hotelCheckinDate string YYYY-MM-DD The hotel checkin date of the expense.
hotelCheckoutDate string YYYY-MM-DD The hotel checkout date of the expense.
startLocation string - Location where the travel started. Maximum length: 100 characters
ticketNumber string - The ticket number associated with the travel. Maximum length: 32 characters

TravelAllowance

Name Type Format Description
dailyLimitAmount number double The allowed amount based on government travel allowance rates.
dailyTravelAllowanceId string - The fixed daily travel allowance ID associated with the expense. Maximum length: 32 characters
isExpensePartOfTravelAllowance boolean true/false Whether the expense is part of travel allowance. Default value: false

Vendor

Name Type Format Description
description string - The description of the vendor. Maximum length: 64 characters
id string - The unique identifier of the vendor.
name string - The name of the vendor (localized as per accept-language header).

UpdateReportExpense

Name Type Format Description
approverAdjustedAmount Amount - The total amount adjusted for the expense by the approver.
authorizationRequestExpenseId string - The authorization request expense ID associated with the expense.
budgetAccrualDate string YYYY-MM-DD The budget accrual date.
businessPurpose string - The text input for the business purpose by the user. Maximum length: 64 characters
comment string - A comment that describes the expense. Maximum length: 2000 characters
customData CustomData - The details from the customData fields. These fields may not have data, depending on the configuration.
exchangeRate ExchangeRate - The exchange rate data for the expense.
expenseSource string - Required The source of the expense. Supported values: EA - Expense Assistant, MOB - Mobile, OTHER - Unknown, SE - Smart Expense, TA - Travel Allowance, TR - Travel Request, UI - Web UI
expenseType ExpenseType - The expense type data for the expense.
hasMissingReceiptDeclaration boolean true/false Whether the expense has an affidavit declaration for missing receipt.
isCopyDownInherited boolean true/false If true, any change in the report expense fields will be copied down to itemizations and allocations, as per the configuration.
isExcludedFromCashAdvanceByUser boolean true/false Whether the user has excluded the expense from cash advance.
isExpenseBillable boolean true/false Whether the expense is billable.
isExpenseRejected boolean true/false Whether the approver or processor has rejected this expense in the report. If true, then this expense will be sent back to the report submitted in an addendum (split) report.
isPaperReceiptReceived boolean true/false Whether paper receipts have been received for the expense.
isPersonalExpense boolean true/false Whether the expense is marked as personal (non-reimbursable) by the user.
jptRouteId string - The unique route ID to identify a Japan rail route.
location Location - The location data of the expense.
merchantTaxId string - The merchant tax ID for the expense. Maximum length: 64 characters
mileage Mileage - The mileage data associated with the expense.
paymentType PaymentType - The payment type data for the expense. Default: CASH
receiptImageId string - The unique identifier of the image associated with the expense.
receiptType ReceiptType - Receipt type for the expense.
smartExpense SmartExpense - The smart expense data associated with this expense.
tax Tax - The tax data associated with the expense.
taxRateLocation string - Transaction location relative to the employee's home location as defined by their user profile. Supported values: FOREIGN - The expense transaction took place in foreign currency, HOME - The expense transaction took place in the reimbursement currency, OUT_OF_PROVINCE - The expense transaction took place outside the state jurisdiction
transactionAmount Amount - The amount of the expense, in the transaction currency paid to the vendor.
transactionDate string YYYY-MM-DD The transaction date (ISO-8601) of the expense.
travel Travel - The travel data associated with the expense.
travelAllowance TravelAllowance - The travel allowance data associated with the expense.
vendor Vendor - The vendor data for the expense.

SmartExpense

Name Type Format Description
creditCardTransactionId string - The unique identifier of the credit card transaction (indexed transactionId) associated with the expense.
ereceipt EReceipt - EReceipt information for the expense.
expenseAttendees ExpenseAttendees - The attendee details associated with the smart expense.
isAutoCreated boolean true/false Whether this expense is auto-created. This element only applies to POST expense request. Default: false
personalCardTransactionId string - The unique identifier of the personal card transaction associated with the expense.
quickExpenseId string - The unique identifier of the mobile expense associated with the expense. When quickExpenseId is specified, the exchangeRate.value field value will be ignored and its value will be read from exchange rate currency service. exchangeRate.operation will still be honored.
trip Trip - Trip data associated with the expense.

Tax

Name Type Format Description
expenseTax1 ExpenseTax - Required The tax data for the expense.
expenseTax2 ExpenseTax - The tax data for the expense.

ExpenseTax

Name Type Format Description
customData CustomData - The details from the customData fields. These fields may not have data, depending on the configuration.
reclaimCode string - The tax reclaim code. Maximum length: 20 characters
reclaimTransactionAmount number double The tax reclaim transaction amount.
taxAuthorityId string - Required The unique identifier of the tax authority.
taxAuthorityName string - The name of the tax authority.
taxCode string - The tax code. Maximum length: 20 characters
taxFormId string - The unique identifier of the tax form associated with the expense.
taxLabel string - The localized label of the tax authority.
taxRateTypeId string - The unique identifier of the tax rate type ID.
taxRateTypeName string - The name of the tax rate type.
taxReclaimConfigurationId string - The unique identifier of the tax reclaim configuration ID.
taxTransactionAmount number double The tax transaction amount.

EReceipt

Name Type Format Description
carEReceipt CarEReceipt - The eReceipt car data.
hotelEReceipt HotelEReceipt - The eReceipt hotel data.
id string - Required The unique identifier of the eReceipt with the expense.
imageId string - The unique identifier of the eReceipt image associated with the expense.
templateURL string - The URL of the eReceipt template. Maximum length: 512 characters
type string - Required The type of eReceipt associated with the expense. Supported values: AIR, CAR, GASXX, GENERAL, GRTRN, HOTEL, JPT, MEALS, OFFIC, PRKNG, RAIL, RIDE, SHIPG, TELEC

HotelEReceipt

Name Type Format Description
calculatedDailyRate number double The calculated hotel daily rate.
endDate string YYYY-MM-DD The hotel checkout date.
locationId string - The unique identifier of the location for this hotel.
startDate string YYYY-MM-DD The hotel check-in date.
totalAmountPaid Amount - The total amount paid.
vendorName string - The name of the hotel vendor. Maximum length: 255 characters. Examples: Hilton, Four Points by Sheraton, Seattle

CarEReceipt

Name Type Format Description
calculatedDailyRate number double The calculated car rental daily rate.
carClass string - The car class. Maximum length: 4 characters. Examples: IDAD, ECMZ, PCAV, IGDV
currencyCode string - The 3-letter ISO 4217 currency code. Examples: USD - US dollars, BRL - Brazilian real, CAD - Canadian dollar
endDate string YYYY-MM-DD The car rental end date.
fuelServiceCharge number double The fuel service charge. Minimum value: 0
numberOfRentalDays integer int32 The number of car rental calculated days. Minimum value: 0
startDate string YYYY-MM-DD The car rental start date.
unitsDriven integer int32 The total units driven. Minimum value: 0
vendorName string - The name of the car vendor. Maximum length: 255 characters. Example: ABC Rent A Car

ExpenseAttendee

Name Type Format Description
associatedAttendeeCount integer int32 The count of total attendees. A count greater than one (1) means there are unnamed attendees associated with this expense-attendee record. Default : 1
attendeeId string - Required The unique identifier of the associated expense attendee within SAP Concur solutions.
customData CustomData - The details from the customData fields. These fields may not have data, depending on the configuration.
isAmountUserEdited boolean true/false This field indicates if the amount value for the attendee on this expense was ever manually edited by the end user. Default: false
isTraveling boolean true/false Whether the attendee was traveling when the expense was incurred. Used for FBT tax calculations.
transactionAmount number double The portion of the expense transaction amount assigned to this attendee for both individual expense tracking and attendee totals across time periods.
versionNumber integer int32 The version number of the attendee. This field value may always be one (1), depending on the configuration. Default: 1

ExpenseAttendees

Name Type Format Description
expenseAttendeeList ExpenseAttendee - The list of attendees associated with the expense. Maximum attendees: 500
noShowAttendeeCount integer int32 The number of attendees that were planned but did not show up. Default value: 0

Trip

Name Type Format Description
airTrip AirTrip - Air trip data associated with the expense.
bookingOrigin string - Booking origin of the trip. Supported values: AETM - Amadeus E-Travel, CLIQ - Concur Travel, PANM - Open Booking, TRPT - TripIt, TSUP - Travel Supplier
bookingSource string - Booking source of the trip. Maximum length: 48 characters. Examples: Expedia, Travelocity, Manual
carTrip CarTrip - Car trip data associated with the expense.
cliqbookPaymentId integer int32 Cliqbook payment ID associated with the trip.
cliqbookPaymentMethod string - Cliqbook payment method associated with the trip. Supported values: GHOST_CARD or FLGHT_PASS
hotelTrip HotelTrip - Hotel trip data associated with the expense.
merchantCode string - Merchant code associated with the trip. Maximum length: 4 characters
rideTrip RideTrip - Ride or taxi trip data associated with the expense.
segmentId integer int64 Required The unique identifier of the segment associated with the expense.
segmentTypeId string - Required Segment type ID associated with the trip. Supported values: AIRFR - Air Ticket, AIRSU - Air Subscription, CARRT - Car Rental, DININ - Dining, EVENT - Event, HOTEL - Hotel Reservation, INSUR - Insurance, LIMOF - Limousine Reservation, MISC - Miscellaneous, PARKG - Parking Fee, RAILF - Train Ticket, RAISU - Train Subscription, TAXIF - Taxi Fare, VISA - Visa
startLocationId string - The unique identifier of the start location associated with the trip.
tripId integer int64 Required The unique identifier of the trip ID associated with the expense.

HotelTrip

Name Type Format Description
calculatedDailyRate number double The calculated hotel daily rate.
endDate string YYYY-MM-DD The hotel checkout date.
numberOfNights integer int32 The number of nights. Minimum value: 1
numberOfRooms integer int32 The number of hotel rooms. Minimum value: 1
startDate string YYYY-MM-DD The hotel check-in date.
totalAmountPaid Amount - The total amount paid.
vendorName string - The name of the hotel vendor. Maximum length: 255 characters. Examples: Hilton, Four Points by Sheraton, Seattle

AirTrip

Name Type Format Description
airlineName string - The name of the airline vendor. Maximum length: 255 characters. Example: Alaska Airlines
endDate string YYYY-MM-DD The last travel date or the travel end date.
numberOfTravelDays integer int32 The number of days of travel. Minimum value: 1
startDate string YYYY-MM-DD The first travel date or the travel start date.
ticketType string - The airline class of service. Maximum length: 10 characters. Example: Economy
totalAmountPaid Amount - The total amount paid.

RideTrip

Name Type Format Description
startDate string YYYY-MM-DD The start date for the ride.
totalAmountPaid Amount - The total amount paid.
vendorName string - The name of the vendor. Maximum length: 255 characters. Example: Yellow Cab

CarTrip

Name Type Format Description
calculatedDailyRate number double The calculated car rental daily rate.
carClass string - The car class. Maximum length: 10 characters. Examples: IDAD, ECMZ, PCAV, IGDV
endDate string YYYY-MM-DD The car rental end date.
numberOfCars integer int32 The number of cars rented. Minimum value: 1
numberOfRentalDays integer int32 The number of car rental calculated days. Minimum value: 0
startDate string YYYY-MM-DD The car rental start date.
totalAmountPaid Amount - The total amount paid.
vendorName string - The name of the car vendor. Maximum length: 255 characters. Example: ABC Rent A Car
Name Type Format Description
deprecation string - -
href string - Required The URL of the related HATEOAS link that you can use for subsequent calls.
hreflang string - -
isTemplated boolean true/false Required Whether the href is parameterized.
media string - -
method string - Required The HTTP method required for the related call.
rel string - Required The link relationship that describes how the href relates to the API call.
title string - -
type string - -

ErrorMessage

Name Type Format Description
errorId string - The unique identifier of the error associated with the response.
errorMessage string - Required The detailed error message.
httpStatus string - Required The http response code and phrase for the response.
path string - Required The URI of the attempted request.
timestamp string date-time Required The time when the error was captured.
validationErrors ValidationError - The validation error messages.

ValidationError

Name Type Format Description
id string - The ID of the validation error.
message string - The detailed message of the validation error.
source string - The type of validation which failed.

Reports v4

The Reports v4 API can be used to read and modify an expense report header of an existing expense report. This API can be used to change attributes like report name, business purpose, etc.

Limitations: This API is only available to partners who have been granted access by SAP Concur. Access to this documentation does not provide access to the API.

Prior Versions

Products and Editions

Scope Usage

Required Scopes:

Name Description Endpoint
expense.report.read Get information about expense reports. GET
expense.report.readwrite Read and write expense report headers. PATCH
expense.report.workflowstatus.write Approve or Send Back the Report in the workflow PATCH
user.read Get User Information, necessary for userID. GET

Optional Scope:

Name Description Endpoint
spend.listitem.read Read only access to spend list items listItemId. GET
spend.list.read Read only access to spend list and category details. GET

Dependencies

SAP Concur clients must purchase Concur Expense in order to use this API. This API requires the Identity v4 API which is currently only available to approved early access partners. Please contact your SAP Concur representative for more information.

Access Token Usage

This API supports both company level and user level access tokens.

Retrieve a Report by ID

Retrieves the details of the specific report header.

Scopes

expense.report.read - Refer to Scope Usage for full details.

Request

URI Template

https://{datacenterURI}/expensereports/v4/users/{userID}/context/{contextType}/reports/{reportId}

Parameters

Name Type Format Description
userID string - Required The unique identifier of the SAP Concur user. Use Identity v4 API to retrieve the userID.
contextType string - Required The access level of the SAP Concur user, which determines the form fields they can view/modify. Supported values: TRAVELER, PROXY
reportId string - Required The unique identifier of the report that is being read.

Headers

Response

Status Codes

Headers

Payload

Example

Request

curl --location --request GET 'https://us.api.concursolutions.com/expensereports/v4/users/32C2FCC3-B2E8-4907-9672-5B3F49B1C643/context/TRAVELER/reports/764428DD6A664AF0BFCB' \
--header 'Authorization: Bearer {access_token}' \
--header 'Concur-CorrelationId: Expense-Report-test' \
--header 'Content-Type: application/json'

Response

200 OK

{
    "approvalStatus": "Not Submitted",
    "approvalStatusId": "A_NOTF",
    "concurAuditStatus": "NOTR",
    "customData": [
        {
            "id": "custom15",
            "value": "4366A89A916F074099A971B000989A94",
            "isValid": true,
            "listItemUrl": "https://us.api.concursolutions.com/list/v4/items?id=4366A89A916F074099A971B000989A94"
        },
        {
            "id": "custom16",
            "value": "Test33224ASDF",
            "isValid": true,
            "listItemUrl": null
        },
        {
            "id": "custom3",
            "value": "582AE31D0F506C4BAA97573F2A90F03B",
            "isValid": true,
            "listItemUrl": "https://us.api.concursolutions.com/list/v4/items?id=582AE31D0F506C4BAA97573F2A90F03B"
        },
        {
            "id": "custom4",
            "value": "79AE45D0F6757946AC2B01CDFA6CA326",
            "isValid": true,
            "listItemUrl": "https://us.api.concursolutions.com/list/v4/items?id=79AE45D0F6757946AC2B01CDFA6CA326"
        }
    ],
    "ledger": "DEFAULT",
    "ledgerId": "2703E3FBD393DA4484ED3CB07303407C",
    "paymentStatus": "Not Paid",
    "paymentStatusId": "P_NOTP",
    "submitDate": null,
    "approvedAmount": {
        "value": 525.00000000,
        "currencyCode": "USD"
    },
    "claimedAmount": {
        "value": 525.00000000,
        "currencyCode": "USD"
    },
    "amountCompanyPaid": {
        "value": 0E-8,
        "currencyCode": "USD"
    },
    "paymentConfirmedAmount": {
        "value": 0E-8,
        "currencyCode": "USD"
    },
    "amountDueCompany": {
        "value": 0E-8,
        "currencyCode": "USD"
    },
    "amountDueCompanyCard": {
        "value": 0E-8,
        "currencyCode": "USD"
    },
    "amountDueEmployee": {
        "value": 0E-8,
        "currencyCode": "USD"
    },
    "personalAmount": {
        "value": 0E-8,
        "currencyCode": "USD"
    },
    "reportTotal": {
        "value": 525.00000000,
        "currencyCode": "USD"
    },
    "amountNotApproved": {
        "value": 0E-8,
        "currencyCode": "USD"
    },
    "isFinancialIntegrationEnabled": false,
    "canReopen": false,
    "isReopened": false,
    "isReceiptImageAvailable": false,
    "isReceiptImageRequired": true,
    "isPaperReceiptsReceived": false,
    "reportId": "764428DD6A664AF0BFCB",
    "currency": "US, Dollar",
    "currencyCode": "USD",
    "analyticsGroupId": "C8CB395275EC4FE9AF6CD5B535EA2B17",
    "hierarchyNodeId": "0F941E0B0A2C974EB2B06CDA67973052",
    "allocationFormId": "FD7E9C6389EF495B85042319D58CAE53",
    "links": [
        {
            "rel": "self",
            "href": "https://us.api.concursolutions.com/expensereports/v4/users/32C2FCC3-B2E8-4907-9672-5B3F49B1C643/context/TRAVELER/reports/764428DD6A664AF0BFCB",
            "hreflang": null,
            "media": null,
            "title": null,
            "type": null,
            "deprecation": null,
            "method": "GET",
            "isTemplated": false
        }
    ],
    "reportDate": "2020-03-25",
    "reportFormId": "674B67F0C6BD4E9CA5D91AFB82CC8ABB",
    "businessPurpose": "Facility cleaning and renovation",
    "countryCode": "US",
    "countrySubDivisionCode": "US-WA",
    "policyId": "EE095F66AEF52B4A9CE62952601E5CB1",
    "startDate": "2020-03-10",
    "endDate": "2020-03-14",
    "name": "March Expenses",
    "policy": "JH - US Expense Policy",
    "country": "UNITED STATES",
    "userId": "32c2fcc3-b2e8-4907-9672-5b3f49b1c643",
    "reportType": "Regular",
    "redirectFund": null,
    "creationDate": "2020-03-25T20:42:39Z",
    "canRecall": false,
    "reportVersion": 0
}

Update a Specific Report

Updates the attributes of a specific report.

Scopes

expense.report.readwrite - Refer to Scope Usage for full details.

Request

URI Template

https://{datacenterURI}/expensereports/v4/users/{userID}/context/{contextType}/reports/{reportId}

Parameters

Name Type Format Description
userID string - Required The unique identifier of the SAP Concur user. Use Identity v4 API to retrieve the userID.
contextType string - Required The access level of the SAP Concur user, which determines the form fields they can view/modify. Supported values: TRAVELER, PROXY
reportId string - Required The unique identifier of the report that is being modified.

Headers

REST Design Specification

PATCH operations in Expense Reports v4 conform to the JSON Merge Patch specification:

Payload

Response

Status Codes

Headers

Payload

Example

Request

curl --location --request PATCH 'https://us.api.concursolutions.com/expensereports/v4/users/32C2FCC3-B2E8-4907-9672-5B3F49B1C643/context/TRAVELER/reports/764428DD6A664AF0BFCB' \
--header 'Authorization: Bearer {access_token}' \
--header 'Concur-CorrelationId: Viswa test' \
--header 'Content-Type: application/json' \
--data-raw '{
    "customData": [
        {
            "id": "custom15",
            "value": "E31CB42509F9FF408BA7DD6713AB49BD",
            "isValid": true
        }
    ],
    "businessPurpose":"Office Facility Supplies",
    "reportSource":"OTHER"
}'

Response

204 No Content

Approve or Send Back a Report

The Approve function advances the specified report to the next step if it is in a system step. The Send Back function sends back the specified report to report owner .

Scopes

expense.report.workflowstatus.write - Refer to Scope Usage for full details.

Request

URI Template

https://{datacenterURI}/expensereports/v4/reports/{reportId}/approve
https://{datacenterURI}/expensereports/v4/reports/{reportId}/sendBack

Parameters

Name Type Format Description
reportId string - Required The unique identifier of the report that is being approved or sent back.

Headers

REST Design Specification

PATCH operations in Expense Reports v4 conform to the JSON Merge Patch specification:

Payload

Response

Status Codes

Headers

Payload

Example

Request

curl --location --request PATCH 'https://us.api.concursolutions.com/expensereports/reports/764428DD6A664AF0BFCB/Approve' \
--header 'Authorization: Bearer {access_token}' \
--header 'Concur-CorrelationId: Viswa test' \
--header 'Content-Type: application/json' \
--data-raw '{
    "reportSource":"OTHER"
}'

Response

204 No Content

Schema

ReportDetails

Name Type Format Description
allocationFormId string - The unique identifier of the allocation form.
amountCompanyPaid Amount - Required The amount paid by the company.
amountDueCompany Amount - Required The amount that the employee owes the company.
amountDueCompanyCard Amount - Required The amount that the employee/company owes the corporate card.
amountDueEmployee Amount - Required The amount that the company owes the employee.
amountNotApproved Amount - Required The amount that was not approved for the report.
analyticsGroupId string - Required The unique identifier of the business intelligence hierarchy node.
approvalStatus string - Required The report’s approval status, in the user’s language.
approvalStatusId string - Required The unique identifier of the approval status.
approvedAmount Amount - Required The total amount of approved expenses in the report.
businessPurpose string - The text input for the business purpose by the user.
canRecall boolean true/false Required Whether the report can be recalled by the current user.
canReopen boolean true/false Whether the report can be reopened after payment.
cardProgramStatementPeriodId string - The unique identifier of card program statement period on the report.
claimedAmount Amount - Required The total amount of all non-personal expenses in the report.
concurAuditStatus string - Required The status of audit for the report.
country string - The country name associated with the report (localized as per accept-language header).
countryCode string ISO 3166-1 alpha-2 country code The report country. Maximum characters: 2. Example: US - United States
countrySubDivisionCode string - The location country sub division ISO 3166-2 code.
creationDate string YYYY-MM-DDTHH:mm:ssZ Required The UTC datetime when the user created the report.
currency string - Required The currency name for the report (localized as per accept-language header).
currencyCode string - Required The 3-letter ISO 4217 currency code for the expense report currency. Examples: USD - US dollars; BRL - Brazilian real; CAD - Canadian dollar; CHF - Swiss franc; EUR - Euro; GBO - Pound sterling; HKD - Hong Kong
customData CustomData - The details from the customData fields. These fields may not have data, depending on the configuration.
endDate string YYYY-MM-DD The end date (ISO-8601) of the report as used for trip-based reporting.
hierarchyNodeId string - Required The unique identifier of the group hierarchy node for the report resource.
isFinancialIntegrationEnabled boolean true/false Required Whether the Financial Integration setting has been enabled for this report.
isPaperReceiptsReceived boolean true/false Required Whether paper receipts have been received for the report.
isReceiptImageAvailable boolean true/false Required Whether the receipt image is available at the report level.
isReceiptImageRequired boolean true/false Required Whether the receipt image is required at the report level.
isReopened boolean true/false Whether the report is reopened.
ledger string - Required The ledger name to which the report belongs (localized as per accept-language header).
ledgerId string - Required The unique identifier of the ledger.
links Link - Resource links related to this call.
name string - Required The expense report name input by the user.
paymentConfirmedAmount Amount - Required The amount that was paid on the report.
paymentStatus string - Required The report's payment status in the user's language.
paymentStatusId string - Required The unique identifier of the payment status of the report.
personalAmount Amount - Required The total amount of expenses marked as personal on the report.
policy string - Required The policy name to which the report adheres (localized as per accept-language header).
policyId string - Required The unique identifier of the policy that applies to this report.
redirectFund RedirectFund - Funds redirected to IBCP card.
reportDate string YYYY-MM-DD The date assigned to the report by the user.
reportFormId string - Required The unique identifier of the report form.
reportId string - Required The unique identifier for the report resource.
reportNumber string - User friendly unique identifier for the report.
reportTotal Amount - Required The total amount on the report.
reportType string - This value identifies the method used to create the report. Statement refers to company billed statement reports and auto-created refers to reports created by Expense Assistant.
reportVersion integer int32 Required The current version of the report.
startDate string YYYY-MM-DD The start date of the report as used for trip-based reporting.
submitDate string YYYY-MM-DDTHH:mm:ssZ The UTC datetime when the user submitted the report.
submitterId string - The unique identifier of the employee who submitted the report.
taxConfigId string - The The tax config ID of the report.
userId string - Required The unique identifier of the Concur user who is the report owner.

UpdateReport

Name Type Format Description
businessPurpose string - The text input for the business purpose by the user.
comment string - The expense report comment added by the user.
country string - The country name associated with the report (localized as per accept-language header).
countryCode string - The location country ISO 3166-1 code.
countrySubDivisionCode string - The location country sub division ISO 3166-2 code.
customData CustomData - The details from the customData fields. These fields may not have data, depending on the configuration.
endDate string YYYY-MM-DD The end date of the report as used for trip-based reporting.
isCopyDownInherited boolean true/false If true, any change in the report header fields will be copied down to expenses, itemizations and allocations, as per the configuration. Usage of this flag should be deliberate as data corruption could result.
isPaperReceiptsReceived boolean true/false Whether paper receipts have been received for the report.
name string - The expense report name input by the user.
policy string - The policy name to which the report adheres to.
policyId string - The unique identifier of the policy that applies to this report.
redirectFund RedirectFund - Funds redirected to IBCP card.
reportDate string YYYY-MM-DD The date assigned to the report by the user.
reportSource string - Required The source of the report. Supported values: EA - Expense Assistant, MOB - Mobile, OTHER - Unknown, SE - Smart Expense, TR - Travel Request, UI - Web UI
startDate string YYYY-MM-DD The start date of the report as used for trip-based reporting.

CustomData

Name Type Format Description
id string - Required The unique identifier of the custom field. Examples: custom1, orgUnit1
isValid boolean true/false Whether the value returned is valid or not. This value is returned for custom fields of all data types and is specifically evaluated for list items to represent the current status. Default: true
value string - The value of the custom field. This field can have values for all the supported data types such as text, integer, boolean and listItemId. Maximum length: 48 characters

Amount

Name Type Format Description
currencyCode string - Required The 3-letter ISO 4217 currency code for the expense report currency, based on the user's assigned reimbursement currency when the report was created. Examples: USD - US dollars; BRL - Brazilian real; CAD - Canadian dollar; CHF - Swiss franc; EUR - Euro; GBO - Pound sterling; HKD - Hong Kong dollar; INR - Indian rupee; MXN - Mexican peso; NOK - Norwegian krone; SEK - Swedish krona
value number double Required The amount in the defined currency.

RedirectFund

Name Type Format Description
amount Amount - Required The value of funds redirected to the IBCP card account.
creditCardId string - Required The unique identifier of the IBCP card account to which funds need to be redirected.

ReportSendBackRequest

Name Type Format Description
comment string - Required Comments for sending back the report.
currentProcessInstanceId string - Current workflow process instance ID for validation.
currentSequence integer int32 Current workflow process sequence number for validation.
reasonCodeId string - The unique identifier of the Reason Code only by processor.
reportSource string - The source of the report. Supported values: EA - Expense Assistant, MOB - Mobile, OTHER - Unknown, SE - Smart Expense, TR - Travel Request, UI - Web UI

ReportApproveRequest

Name Type Format Description
comment string - Approver comments.
currentProcessInstanceId string - Current workflow process instance ID for validation.
currentSequence integer int32 Current workflow process sequence number for validation.
reportSource string - The source of the report. Supported values: EA - Expense Assistant, MOB - Mobile, OTHER - Unknown, SE - Smart Expense, TR - Travel Request, UI - Web UI
statusId string - Status that will be assigned to the report by this workflow transition.
Name Type Format Description
deprecation string - -
href string - Required The URL of the related HATEOAS link that you can use for subsequent calls.
hreflang string - -
isTemplated boolean true/false Required Whether the href is parameterized.
media string - -
method string - Required The HTTP method required for the related call.
rel string - Required The link relationship that describes how the href relates to the API call.
title string - -
type string - -

ErrorMessage

Name Type Format Description
errorId string - The unique identifier of the error associated with the response.
errorMessage string - Required The detailed error message.
httpStatus string - Required The http response code and phrase for the response.
path string - Required The URI of the attempted request.
timestamp string date-time Required The time when the error was captured.
validationErrors ValidationError - The validation error messages.

ValidationError

Name Type Format Description
id string - The ID of the validation error.
message string - The detailed message of the validation error.
source string - The type of validation which failed.

Workflows v4

Important: This API is currently in pre-release status and is only available to approved early access participants. The API is under development and might change before being generally released. To become an early access participant, contact your SAP Concur Representative.

The Workflows v4 API is used to Approve or Send Back an expense report that is in the workflow. This API is used only for normal approval steps and not for Cost Object Approval steps.

Limitations: This API is only available to partners who have been granted access by SAP Concur. Access to this documentation does not provide access to the API.

Prior Versions

Products and Editions

Scope Usage

Required Scope:

Name Description Endpoint
expense.report.workflowstatus.write Approve or Send Back the Report in the workflow PATCH

Optional Scope:

Name Description Endpoint
expense.report.read Get information about expense reports. GET
expense.report.readwrite Read and write expense report headers. PATCH
spend.listitem.read Read only access to spend list items listItemId. GET
spend.list.read Read only access to spend list and category details. GET
user.read Get User Information, necessary for userID. GET

Dependencies

SAP Concur clients must purchase Concur Expense in order to use this API. This API requires the Identity v4 API which is currently only available to approved early access partners. Please contact your SAP Concur representative for more information.

Access Token Usage

This API supports both company level and user level access tokens.

Approve or Send Back a Report

The Approve function advances the specified report to the next step if it is in a system step. The Send Back function sends back the specified report to report owner.

Scopes

expense.report.workflowstatus.write - Refer to Scope Usage for full details.

Request

URI Template

https://{datacenterURI}/expensereports/v4/reports/{reportId}/approve
https://{datacenterURI}/expensereports/v4/reports/{reportId}/sendBack

Parameters

Name Type Format Description
reportId string - Required The unique identifier of the report that is being approved or sent back.

Headers

REST Design Specification

PATCH operations in Expense Reports v4 conform to the JSON Merge Patch specification:

Payload

Response

Status Codes

Headers

Payload

Example

Request

curl --location --request PATCH 'https://us.api.concursolutions.com/expensereports/reports/764428DD6A664AF0BFCB/Approve' \
--header 'Authorization: Bearer {access_token}' \
--header 'Concur-CorrelationId: Viswa test' \
--header 'Content-Type: application/json' \
--data-raw '{
    "reportSource":"OTHER"
}'

Response

204 No Content

Schema

ReportSendBackRequest

Name Type Format Description
comment string - Required Comments for sending back the report.
currentProcessInstanceId string - Current workflow process instance ID for validation.
currentSequence integer int32 Current workflow process sequence number for validation.
reasonCodeId string - The unique identifier of the Reason Code only by processor.
reportSource string - The source of the report. Supported values: EA - Expense Assistant, MOB - Mobile, OTHER - Unknown, SE - Smart Expense, TR - Travel Request, UI - Web UI

ReportApproveRequest

Name Type Format Description
comment string - Approver comments.
currentProcessInstanceId string - Current workflow process instance ID for validation.
currentSequence integer int32 Current workflow process sequence number for validation.
reportSource string - The source of the report. Supported values: EA - Expense Assistant, MOB - Mobile, OTHER - Unknown, SE - Smart Expense, TR - Travel Request, UI - Web UI
statusId string - Status that will be assigned to the report by this workflow transition.

Error

Name Type Format Description
errorId string - The unique identifier of the error associated with the response.
errorMessage string - Required The detailed error message.
httpStatus string - Required The http response code and phrase for the response.
path string - Required The URI of the attempted request.
timestamp string date-time Required The time when the error was captured.
validationErrors ValidationError - The validation error messages.

ValidationError

Name Type Format Description
id string - The ID of the validation error.
message string - The detailed message of the validation error.
source string - The type of validation which failed.

Quick Expense v4

The Quick Expense API can be used to create an expense with basic information such as date, amount, and expense type, with or without a receipt image. This expense can be added to an expense report within Concur Expense, allowing the user to provide additional details such as attendees, itemizations etc.

Limitations: This API is only available to partners who have been granted access by SAP Concur. Access to this documentation does not provide access to the API. This API is not available in Implementation environments.

Products and Editions

Scope Usage

Required Scopes:

Name Description Endpoint
quickexpense.writeonly Write quick expense. POST
user.read Get User Information, necessary for userID. POST
receipts.writeonly Required if e-Bunsho is enabled Write quick expense. POST

Optional Scope:

Name Description Endpoint
CONFIG Get Expense Configuration information, necessary for expenseTypeId. POST

Dependencies

SAP Concur clients must purchase Concur Expense in order to use this API. This API requires the User v3.1 API which is currently only available to approved early access partners. Please contact your SAP Concur representative for more information.

The partner may use the following SAP Concur APIs to get optional information: * Expense Group Configurations v3.0, to retrieve the expenseTypeId * Locations v3.0, to retrieve the location id

Japan Market: If the partner is using this API to provide the e-Bunsho digital timestamp for the receipt, the partner should confirm that the client has e-Bunsho activated in SAP Concur.

Access Token Usage

This API supports both company level and user level access tokens.

Create a Quick Expense

Creates a quick expense without an image.

Scopes

quickexpense.writeonly - Refer to Scope Usage for full details.

Request

URI

Template
https://{datacenterURI}/quickexpense/v4/users/{userID}/context/{contextType}/quickexpenses
Parameters
Name Type Format Description
userID string - Required The unique identifier of the SAP Concur user. Use User Profile v1.0 to retrieve the userID.
contextType string - Required The access level of the SAP Concur user, which determines the form fields they can view/modify. Supported value: TRAVELER.

Headers

Payload

Response

Status Codes

Headers

Payload

Example

Request

curl -X POST \
  https://us.api.concursolutions.com/quickexpense/v4/users/184dd31a-f48a-4103-879f-c8d45456c7cd/context/TRAVELER/quickexpenses \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Content-Type: application/json' \
  -H 'concur-correlationid: quick-expense-test' \
  -d '{
  "comment": "Offsite team lunch.",
  "expenseTypeId": "BUSML",
  "entryDetails": "test-entry",
  "location": {
    "city": "Bellevue",
    "countryCode": "US",
    "countrySubDivisionCode": "US-WA",
    "id": "",
    "name": ""
  },
  "paymentTypeId": "CASHX",
  "transactionAmount": {
    "currencyCode": "USD",
    "value": 88.05
  },
  "transactionDate": "2019-02-04"
}'

Response

201 Created

{
    "quickExpenseIdUri": "https://seapr1qes.concurasp.com/quickexpense/v4/users/184dd31a-f48a-4103-879f-c8d45456c7cd/context/TRAVELER/quickexpenses/E018795D2B09094FBF223E209E921B88"
}

Create a Quick Expense with an Image

Creates a quick expense with an image.

Scopes

quickexpense.writeonly - Refer to Scope Usage for full details. receipts.writeonly - Refer to Scope Usage for full details.

Request

URI

Template
https://{datacenterURI}/quickexpense/v4/users/{userID}/context/{contextType}/quickexpenses/image
Parameters
Name Type Format Description
userID string - Required The unique identifier of the SAP Concur user. Use User Profile v1.0 to retrieve the userID.
contextType string - Required The access level of the SAP Concur user, which determines the form fields they can view/modify. Supported values: TRAVELER.
fileContent file - Required The quick expense image. Maximum size 5 MBs. Supported image types are: PNG, PDF, TIFF, JPEG

Headers

Payload

Response

Status Codes

Headers

Payload

Example

Request

curl -X POST \
  https://us.api.concursolutions.com/quickexpense/v4/users/184dd31a-f48a-4103-879f-c8d45456c7cd/context/TRAVELER/quickexpenses/image \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Content-Type: multipart/form-data' \
  -H 'concur-correlationid: quick-expense-with-image' \
  -H 'content-type: multipart/form-data' \
  -F fileContent=@/Users/i845500/Pictures/Snip20180410_1.png \
  -F 'quickExpenseRequest={
  "comment": "Offsite team lunch.",
  "expenseTypeId": "BUSML",
  "entryDetails": "test-entry",
  "location": {
    "city": "Bellevue",
    "countryCode": "US",
    "countrySubDivisionCode": "US-WA",
    "id": "",
    "name": ""
  },
  "paymentTypeId": "CASHX",
  "transactionAmount": {
    "currencyCode": "USD",
    "value": 88.05
  },
  "transactionDate": "2019-02-04"
}'

Response

201 Created

{
    "quickExpenseIdUri": "https://seapr1qes.concurasp.com/quickexpense/v4/users/184dd31a-f48a-4103-879f-c8d45456c7cd/context/TRAVELER/quickexpenses/A0D1CE97B4692B4F8E29BEA53B250E36"
}

Schema

Quick Expense Request

Name Type Format Description
comment string - This is a comment attached to the quick expense.
entryDetails string - The quick expense entry details.
expenseTypeId string - Required This is the expense type id of quick expense. Use Expense Group Configurations v3.0 to retrieve the supported expense types. Supported values for a null value are: UNDEF, NULL. NULL can only be used on a POST operation and will be converted to UNDEF.
location - Location The location where the quick expense occurred.
paymentTypeId string - This is the payment type id of quick expense. Supported values: CASHX, CPAID, PENDC.
transactionAmount - Amount Required The amount of the quick expense.
transactionDate string YYYY-MM-DD Required This is the transaction date of the quick expense.
vendor string - The name of the vendor.

Location

Name Type Format Description
city string - The location city.
countryCode string - The location country ISO 3166-1 code.
countrySubDivisionCode string - The location country sub division ISO 3166-2 code.
id string - The unique identifier of the location. Use Locations v3.0 to retrieve the location id.
name string - The location name.

Amount

Name Type Format Description
currencyCode string - Required The 3-letter ISO 4217 currency code.
value number - Required The amount value.

Quick Expense Response

Name Type Format Description
quickExpenseIdUri string - The quick expense created resource url.

Error

Name Type Format Description
errorId string - The unique identifier of the error.
errorMessage string - Required Message associated with the error.
httpStatus string - The HTTP status associated with the error.
path string - The path to the resource.
timestamp string - The timestamp for the error.
validationErrors array validationErrors An array of validation errors.

Validation Errors

Name Type Format Description
message string - The validation error message.
source string - The source of the validation error.

Travel Allowance

The Travel Allowance API fetches all the fixed allowance days in the specified expense report. Clients using this API can determine whether an allowance is a full day or partial day allowance.

Limitations: This API is available only for Finland customers. This API is not available in the China Data Center.

Process Flow

Image of Process_Flow

Products and Editions

Scope Usage

Name Description Endpoint
travelallowance.allowancedays.read View the allowance days in an expense report GET
EXPRPT Retrieve the report ID from the Expense Report API to supply to the Travel Allowance API GET

Dependencies

The developer must call the Expense Report v3 API prior to using this API, to get the expense report Id.

Access Token Usage

This API will work with Company access token only. A valid Company access token is needed to use this API.

Retrieve a Company Access Token

A Company-level access token is required to create an integration with this API. This allows your integration to get fixed allowance day details of an expense report.

For clients connecting to this API to build a custom integration you will receive client credentials and information on how to generate your company access token or company refresh token from the SAP Concur Web Services resource assigned to assist you with Authentication.

Before making requests to this API, you must obtain an access token from the Authentication API.

The response will include an access_token field, which contains your access token. For subsequent calls, you will need to include this access token in the Authorization header of your calls.

Get Details of Travel Allowance Days

Scopes

travelallowance.allowancedays.read - Refer to Scope Usage for full details.

Request

URI

Template
https://{datacenterURI}/api/v4/travelallowance/allowancedays/companyUUID/{companyUUID}/contexts/{Context}/{ContextId}
Parameters
Name Type Format Description
companyUUID uuid - Required The company's unique identifier.
Context string - Required For expense reports, the value is EXPENSE_REPORT
ContextId string - Required For expense reports, this is the reportId of the report.

Headers

Payload

Response

Status Codes

Headers

Payload

Example

Request

GET https://us.api.concursolutions.com/api/v4/travelallowance/allowancedays/companyUUID/d5528866-51b1-40a1-bab2-76296a106dcd/contexts/EXPENSE_REPORT/B769E8B106C04F30AE27
Authorization: Bearer {token}
Content-Type: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Content-Length: 1270
{
  "links": [
    {
      "rel": "self",
      "href": "https://us.api.concursolutions.com/api/v4/travelallowance/allowancedays/companyUUID/d5528866-51b1-40a1-bab2-76296a106dcd/contexts/EXPENSE_REPORT/B769E8B106C04F30AE27"
    }
  ],
  "content": [
    {
      "currencyCode": "EUR",
      "fullAllowanceDay": "False",
      "allowanceDate": "2018-09-244T12:00:00",
      "expenseTransactionDate": "2018-09-244T12:00:00",
      "expenseTransactionAmount": 29,
      "expenseTypeCode": "MEALS"
    },
    {
      "currencyCode": "EUR",
      "fullAllowanceDay": "False",
      "allowanceDate": "2018-09-245T12:00:00",
      "expenseTransactionDate": "2018-09-245T12:00:00",
      "expenseTransactionAmount": 29,
      "expenseTypeCode": "MEALS"
    },
    {
      "currencyCode": "EUR",
      "fullAllowanceDay": "False",
      "allowanceDate": "2018-09-246T12:00:00",
      "expenseTransactionDate": "2018-09-246T12:00:00",
      "expenseTransactionAmount": 29,
      "expenseTypeCode": "MEALS"
    }
  ]
}

Schema

Get Travel Allowance Days Response Schema

Name Type Format Description
expenseTypeCode string - Expense Code. For example, MEALS for Travel Allowance.
fullAllowanceDay string - True/False. 'True' means full allowance day and 'False' means partial allowance day.
currencyCode string - The 3-letter ISO 4217 currency code for the expense report currency. The expense report currency is defined as the report creator's default reimbursement currency.
allowanceDate dateTime dateTime Travel Allowance Date.
expenseTransactionDate dateTime dateTime Expense transaction date.
expenseTransactionAmount numeric - Expense transaction amount, in the expense entry currency.
href string - The href represents the target resource identifiers.
rel string - The link relation type describes how the current context (source) is related to the target resource.

Error

Name Type Format Description
exception string - Relative exception details.
timestamp date - Time at which exception occur.
message string - Required Message associated with the error.
path string - Relative data path.

Definitions

Name Type Format Description
dateTime string - DateTime of where the transaction happened in format specified in ISO 8601, using UTC + Offset. For example, 2016-04-22T12:20+0700 (12:20 PM in Pacific Time).

Financial Documents Schemas

Expense

Expense - Employee

Name Type Format Description
employeeCustom1Code through employeeCustom21Code CustomField - The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters.
employeeCustom1Value through employeeCustom21Value CustomField - The details from the custom fields. These fields may not have data, depending on the configuration. If configured as a list, this field contains the name of the list item. Maximum length 64 characters.
employeeFirstName String - Alphanumeric. First name of employee. Maximum length 32 characters.
employeeId String - Alphanumeric. Employee ID often also serves as the employee’s Vendor ID for AP system integrations or payroll ID for payroll integrations. Maximum length 128 characters.
employeeLastName String - Alphanumeric. Last name of employee. Maximum length 32 characters.
employeeMI String - Alphanumeric. Middle initial of employee. Maximum length 1 character.
employeeOrgUnit1Code through employeeOrgUnit6Code CustomField - The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters.
employeeOrgUnit1Value through employeeOrgUnit6Value CustomField - The details from the custom fields. These fields may not have data, depending on the configuration. If configured as a list, this field contains the name of the list item. Maximum length 64 characters.

Expense - Report

Name Type Format Description
cashAdvanceReturnsAmount Number Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field. Currency. Amount of cash advance returned.
employeeCurrencyAlphaCode String 3-letter ISO 4217 alpha code. Alphanumeric. Reimbursement currency.
homeCountryCode String ISO 3166-1 alpha-2 country code. Alphanumeric. The report country. Example: United States is US.
isTest String Y/N Signifies if this report belongs to a test user in system. Y = test user, N = not a test user.
ledgerCode String - Alphanumeric. External accounting system ID. Maximum length 20 characters.
payrollPayIndicator String Y/N This field indicates whether the expense group the report user belongs to is configured to reimburse employees using Payroll.
payrollPaymentClearingAccountCode String - Alphanumeric. SAP customers who reimburse their employees via Payroll need to capture a payroll clearing account code as part of the accounting entry during the financial posting process. Maximum length 128 characters.
reportCreationDate String yyyy-mm-ddThr:min:sec.msZ Date the report was created. Maximum length 24 characters.
reportCustom1Code through reportCustom20Code CustomField - The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters.
reportCustom1Value through reportCustom20Value CustomField - The details from the custom fields. These fields may not have data, depending on the configuration. If configured as a list, this field contains the name of the list item. Maximum length 64 characters.
reportEndDate String yyyy-mm-ddThr:min:sec.msZ End date from the report header. Can be imported from trip data or manually entered.
reportId String Unique (across all SAP Concur clients) 32 character alphanumeric. Alphanumeric. Often used as a voucher number when integrating across AP systems.
reportKey Number - A unique ID (within a single SAP Concur client's company) generated by the system. An alternative to the reportId. Starts with 1 and increments with each expense report. Maximum length 11 characters.
reportName String - Alphanumeric. Report name assigned by employee. Maximum length 40 characters.
reportOrgUnit1Code through reportOrgUnit20Code CustomField - The details from the custom fields. These fields may not have data, depending on the configuration. The second segment in the fully qualified GL string should use Org Unit 2, except the natural account field. The natural account data is stored in column 167 of the SAE. Maximum length 48 characters.
reportOrgUnit1Value through reportOrgUnit20Value CustomField - The details from the custom fields. These fields may not have data, depending on the configuration. If configured as a list, this field contains the name of the list item. Maximum length 64 characters.
reportPaymentProcessingDate String yyyy-mm-ddThr:min:sec.msZ The date that the report completed all approvals and was ready to be extracted for payment. Maximum length 24 characters.
reportStartDate String - Report start date. Maximum length 24 characters.
reportSubmitDate String - Date/time the employee submitted the report for approval. Maximum length 24 characters.
reportUserDefinedDate String - Custom date/time specified by user. Maximum length 24 characters.
revisionNumber Number - Report revision number. This will be used to track changes made to posted expenses. Default value is 1. Maximum length 32 characters.
totalApprovedAmount Number Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field. Total approved amount of the report.
versionId Number - The version of the FI Document, which is the same as the version of the API endpoint. Maximum length 32 characters.

Expense - expenseEntry

Name Type Format Description
cardAccountID String - Alphanumeric. ID for the card account. This can be used by the receiving system to condense transactions associated with this card. Maximum length 32 characters.
cardProgramTypeCode String - Alphanumeric. The code used to identify the card’s program type. Maximum length 5 characters.
cardStatementPeriodEndDate String yyyy-mm-ddThr:min:sec.msZ The date of the end of the statement period. Maximum length 24 characters.
cardStatementPeriodStartDate String yyyy-mm-ddThr:min:sec.msZ The date of the start of the statement period. Maximum length 24 characters.
cardTransactionAmount Number Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field. Currency. Amount of the charge in the spend currency.
cardTransactionCurrency String ISO 4217 3-letter alpha code. Alphanumeric. Currency code for the spend currency.
cardTransactionID String - Reference number from the credit card vendor. Maximum length 32 characters.
cardTransactionPostedAmount Number Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field. Amount of the charge in the billing currency of the card.
cardTransactionPostedCurrency String ISO 4217 3-letter alpha code. Alphanumeric. Currency code for the card billing currency.
clearingAccountCode String - Alphanumeric. Contains the expense type account code. - or - If a CBCP Personal expense, the company card clearing account code. - or - If charge is tied to a Statement Report, and accounting code is set for Company Billed card account, the card's accounting code as specified in the Account Code field when creating or editing a CBS account. Maximum length 20 characters.
entryApprovedAmount Number Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field. Currency. Amount approved in the reimbursement currency.
entryCountryCode String 2-character country code. Alphanumeric. Report entry country code.
entryCountrySubCode String - Alphanumeric. Report entry country sub code. Maximum length 6 characters.
entryCurrAlphaCode String ISO 4217 3-letter alpha code. Alphanumeric. Currency ISO alpha code for the spend currency if not an imported credit card or the invoice currency if this is a credit card. Maximum length 4 characters.
entryCustom1Code through entryCustom40Code CustomField - The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters.
entryCustom1Value through entryCustom40Value CustomField - The details from the custom fields. These fields may not have data, depending on the configuration. If configured as a list, this field contains the name of the list item. Maximum length 64 characters.
entryDate String yyyy-mm-ddThr:min:sec.msZ Date that this expense was incurred (when the money was spent or credit card receipt date).
entryDescription String - Alphanumeric. Expense description as entered by the employee. Maximum length 64 characters.
entryElectronicReceiptId String - GUUID. Electronic receipt ID. Maximum length 24 characters.
entryExchangeRate Number - Rate used to convert from the report entry (spend) currency to the report (reimbursement) currency. Maximum length 23 characters.
entryExchangeRateDirection String M/D Alphanumeric. The direction of the exchange rate conversion. Either: M = Multiply or D = Divide.
entryId String - Report entry sync GUUID unique key. Maximum length 32 characters.
entryIsBillable String Y/N Yes or no is the expense billable.
entryIsPersonal String Y/N Yes or no is the expense personal.
entryLocationCityName String - Alphanumeric. Report entry location city name. Maximum length 64 characters.
entryLocationName String - Alphanumeric. Report entry location name. Maximum length 64 characters.
entryOrgUnit1Value through entryOrgUnit6Value CustomField - The details from the custom fields. These fields may not have data, depending on the configuration. If configured as a list, this field contains the name of the list item. Maximum length 64 characters.
entryOrgUnit1Code through entryOrgUnit6Code CustomField - The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters.
entryReceiptId String - GUUID. Non-electronic receipt image. Maximum length 32 characters.
entryReceiptType String T/R/N Alphanumeric. One of these: T = Tax receipt, R = Regular receipt, or N = No receipt.
entrySupplierTaxID String - Alphanumeric. Report entry XML receipt supplier tax ID. Maximum length 64 characters.
entryUuid String - Report Entry XML Receipt UUID. Maximum length 32 characters.
entryVendorCode String - Alphanumeric. Vendor name list short code. Maximum length 32 characters.
entryVendorDescription String - Alphanumeric. Vendor description. Maximum length 64 characters.
expensePayIndicator String Either: 1 = Expense Pay or blank = not Expense Pay. Indicates whether Expense Pay reimbursed this journal entry.
expenseTypeCode String - Alphanumeric. Code for the expense type. Maximum length 5 characters.
expenseTypeName String - Alphanumeric. Expense type name. Maximum length 64 characters.
legacyEntryId Number - Legacy report entry key. Maximum length 11 characters.
liabilityAccountCode String - Alphanumeric. The liability account code assigned to the funding account paying this entry. Maximum length 48 characters.
offsetPayType String Y/N Use Offsets. Y = Yes, N= No.
reportEntryPatKey String - Alphanumeric. Report Entry Payment Code. Maximum length 4 characters.

Expense - Allocation

Name Type Format Description
allocationCustom1Code through allocationCustom20Code CustomField - The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters.
allocationCustom1Value through allocationCustom20Value CustomField - The details from the custom fields. These fields may not have data, depending on the configuration. If configured as a list, this field contains the name of the list item. Maximum length 64 characters.
allocationId String - GUUID. System-generated unique key for this allocation record. Maximuml length 32 characters.
allocationPercentage Number - Percent of the report entry assigned to this allocation record. Maximum length 11 characters.

Expense - Journal

Name Type Format (length) Description
accountingTransactionType String - Alphanumeric. This is the Intuit QuickBooks specific transaction value. It will be null or a value (GJ, CC, or BILL) depending on if it’s a journalpayee or journalpayer. This determines if a transaction should be posted as Bill or Credit Card in QuickBooks. Maximum length 24 characters.
amountGrossCard Number Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field. Amount due to the company card of either CBCP or IBCP type for this detail row.
amountNetOfReclaim Number Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field. Currency. Gross Journal amount subtracting reclaimable tax. Or the Net Journal amount adding non-reclaimable tax.
amountNetOfTax Number Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field. Currency. Allocated net of reclaim tax. You get this by starting from the net and adding the tax that is not reclaimable, or starting with the gross and subtracting reclaimable.
amountTax Number Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field. Currency. This is the Gross Journal amount subtracting the total Tax amount.
cardTransactionReferenceNumber Number - Reference number from the credit card vendor. Maximum length 64 characters.
journalAccountCode String - Alphanumeric. Contains the expense type account code. - or - If a CBCP Personal expense, the company card clearing account code. - or - If charge is tied to a Statement Report, and accounting code is set for Company Billed card account, the card's accounting code as specified in the Account Code field when creating or editing a CBS account. Maximum length 48 characters.
journalPayee String - Alphanumeric. Payment code name for the payee. Maximum length 4 characters.
journalPayer String - Alphanumeric. Payment code name for the payer. Maximum length 4 characters.
taxGuid String - GUUID. Unique identifier associated with the report entry tax allocation. Maximum length 32 characters.

Expense - cashAdvanceApplication

Name Type Format Description
cashAdvanceApplicationAmount Number Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field. Currency. Cash advance utilized amount.
cashAdvanceClearingAccountCode String - Alphanumeric. The Account Code is the clearing account code which was configured for the employee in the profile. Maximum length 48 characters.
cashAdvanceId String - GUUID. Unique system ID assigned to the cash advance. Maximum length 32 characters.
cashAdvanceTransactionType Number - Type of transaction: 1 = Issue or return to administrator, 2 = Application, including cash advance return expense within a report, or 3 = System cash advance, from balance carry forward.

Invoice

Invoice - requestHeader

Name Type Format Description
amountNetInvoice Number - The invoice total amount minus the shipping and tax amounts. Maximum length 23 characters.
amountShippingTotal Number - The value for the shipping amount header field. Maximum length 23 characters.
amountTax Number - The total amount of tax on a given invoice. Maximum length 23 characters.
amountVAT1 through amountVAT4 Number 23 The individual total VAT amounts for the invoice. Maximum length 23 characters.
clearingAccountCode String - Contains the expense type account code. - or - If a CBCP Personal expense, the company card clearing account code. - or - If charge is tied to a Statement Report, and accounting code is set for Company Billed card account, the card's accounting code as specified in the Account Code field when creating or editing a CBS account. Maximum length 20 characters.
currencyAlphaCode String ISO 4217 3-letter alpha code. Currency ISO alpha code for the spend currency if not an imported credit card or the invoice currency if this is a credit card.
deliverySlipNumber String - Delivery slip number of the receipt which is associated to the invoice line item. Maximum length 256 characters.
discountPercentage Number Percentage Percent value that defines the amount of discount that would be applied.
discountTermsDays Number - Numeric value defining the discount term day amount. Maximum length 3 characters.
invoiceDate String YYYY-MM-DD Date of the invoice.
invoicePayIndicator String Y/N- Signifies if this report belongs to a test user in system.
invoiceReceivedDate String YYYY-MM-DD The date on which the invoice was received.
isTest String Y/N Signifies if this report belongs to a test user in system.
ledgerCode String - External accounting system ID. Maximum length 20 characters.
ledgerName String - The general ledger tied to the invoice. Maximum length 100 characters.
multiplePurchaseOrder String Y/N Defines whether or not multiple purchase orders are tied to the invoice.
netPaymentTermDays Number - Numeric value defining the payment term day amount. Maximum length 3 characters.
paymentDueDate String YYYY-MM-DD The date the payment is due for a given invoice.
payMethodType String Drop Down Selector. Valid format options include: ACH, client paid, check, PAYPVD, wire, card, or VCHER. The method used to pay the invoice, as of the point in time the extract is run. NOTE: It is possible for the method to be changed or updated post-extract through either the Payment Confirmation import (if the client controls payments), or through Invoice Pay (using Payment Manager).
postingDate String YYYY-MM-DD The date the invoice will be posted to the ERP system.
processCompleteDate String YYYY-MM-DD The date the invoice was processed.
reqKey Number Integer An integer that uniquely defines this invoice in SAP Concur. This is the value that the Invoice Confirmation Import uses to match to this particular invoice.
requestCreationDate String YYYY-MM-DD The date the invoice was originally saved.
requestCustom1Code through requestCustom24Code CustomField The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters.
requestCustom1Value through requestCustom24Value CustomField - The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters.
requestDescription String - The invoice’s description. Maximum length 250 characters.
requestId String - The unique identification assigned to the invoice. Maximum length 20 characters.
requestOrgUnit1Code through requestOrgUnit6Code CustomField - The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters.
requestOrgUnit1Value through requestOrgUnit6Value CustomField - The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters.
requestTitle String - The invoice name. Maximum length 100 characters.
requestTotal Number Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field. The sum of all Line Item Amounts plus Shipping Amount and Tax Amount for the invoice.
revisionNumber Number - Invoice revision number. Default value is 1. Maximum length 32 characters.
submitDate String YYYY-MM-DD Date/time the employee submitted the invoice for approval.
vendorInvoiceNumber String - The invoice number assigned by the vendor. Maximum length 50 characters.
versionId String - The version of the FI Document, which is the same as the version of the API endpoint. Maximum length 32 characters.

Invoice - ownerEmployee

Name Type Format Description
employeeCustom1Code through employeeCustom21Code CustomField - The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters.
employeeCustom1Value through employleeCustom21Value CustomField - The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters.
employeeFirstName String - First name of employee. Maximum length 32 characters.
employeeId String - Employee ID often also serves as the employee’s Vendor ID for AP system integrations or Payroll ID for Payroll integrations. Maximum length 48 characters.
employeeLastName String - Last name of employee. Maximum length 32 characters.
employeeMI String - Middle initial of employee. Maximum length 1 character.
employeeOrgUnit1Value through employeeOrgUnit6Value CustomField - The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters.

Invoice - Vendor

Name Type Format Description
vendorCode String - The financial system's code for this vendor. Maximum length 23 characters.
vendorContactFirstName String - Buyer contact for the vendor record’s first name. Maximum length 255 characters.
vendorContactLastName String - Buyer contact for the vendor record’s last name. Maximum length 255 characters.
vendorName String - The financial system's name for this vendor. Maximum length 255 characters.
vendorRemitToAddressCode String Less than or equal to 64. The financial system's code for this address.

Invoice - lineItem

Name Type Format Description
allocationAccountCode String - The Account Code for the Allocation related to this Journal Entry. Maximum length 20 characters.
allocationCustom1Code through allocationCustom20Code CustomField - The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters.
allocationCustom1Value through allocationCustom20Value CustomField - The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters.
allocationKey Number - System-generated unique key for this allocation record. Maximum length 13 characters.
allocationPercentage Number - Percent of the report entry assigned to this allocation record. Maximum length 64 characters.
journal String - Container for journal entries tied to the allocation. Maximum length 48 characters.
accountCode Number - The financial system accounting code value tied to the invoice line. Maximum length 20 characters.
amountGross Number - The gross amount (total amount) of the invoice line item. Maximum length 23 characters.
amountNet Number - The net amount of the invoice line item not including shipping and tax. Maximum length 23 characters.
amountShipping Number Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field. The value for the Shipping Amount header field. Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field.
expenseTypeCode String - Code for the expense type so a value that isn’t language dependent is returned. Maximum length is 7 characters.
expenseTypeName String - Expense type name. Maximum length 64 characters.
externalLineItemId String - The PO Line item associated with to the Invoice. Maximum length 100 characters.
lineItemCode String - The Primary Key value for the expense type. Maximum length 7 characters.
lineItemCustom1Code through lineItemCustom20Code CustomField - The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters.
lineItemCustom1Value through lineItemCustom20Value CustomField - The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters.
lineItemDeliverySlipNumber String - Delivery Slip Number of the receipt which is associated to the invoice line item. Maximum length 256 characters.
lineItemDescription String - The description of the goods or services being purchased on the individual invoice line. Maximum length 255 characters.
lineItemPurchaseOrderNumber String - The purchase order number associated with the invoice line item (for a multiple purchase order-based invoice), or the purchase order number associated with the header (for a single purchase order-based invoice). Maximum length 10 characters.
lineItemQuantity String - The quantity of the line item. Maximum length 23 characters.
lineItemSequenceOrder Number Integer Line item number for the line item related to this Journal Entry. Value is dynamically generated by the system based on the number of lines.
lineItemUnitPrice Number - The quantity unit price for the item being purchased. Maximum length 23 characters.
poLineNumber Number - The PO line item number associated to the payment request. Maximum length 48 characters.
receiptNumber Number - The Goods Receipt number. Maximum length 256 characters.
receiptQuantity Number - The Goods Received quantity. Maximum length 23 characters.
receiptItemID Number - The ID of the Goods Receipt tied to the Invoice and PO Line. Maximum length 48 characters.

Invoice - Tax

Name Type Format Description
amountTax Number - The taxation amount that exists on the invoice line. Maximum length 23 characters.
taxCode String - Tax code assigned to this tax authority for the expense type entered on the expense entry. Maximum length 20 characters.
taxField String - Defines which database field the tax resides in. Maximum length 20 characters.

Cash Advance

Cash Advance - employeeData

Name Type Format Description
employeeCustom1Code through employeeCustom21Code CustomField - The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters.
employeeCustom1Value through employeeCustom21Value CustomField - The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 64 characters.
employeeFirstName String - Alphanumeric. First name of employee. Maximum length 32 characters.
employeeId String - Alphanumeric. Employee ID often also serves as the employee’s Vendor ID for AP system integrations or Payroll ID for Payroll integrations. Maximum length 128 characters.
employeeLastName String - Alphanumeric. Last name of employee. Maximum length 32 characters.
employeeMI String - Alphanumeric. Middle initial of employee. Maximum length 1 character.
employeeOrgUnit1Code through employeeOrgUnit6Code CustomField - The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters.
employeeOrgUnit1Value through employeeOrgUnit6Value CustomField - The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 64 characters.

Cash Advance - cashAdvanceData

Name Type Format Description
cardAccountID String - Alphanumeric. ID will be used initially by the receiving system to “condense” transactions associated with this card. It will also be used to retrieve the card number in a separate API call. Maximum length 32 bytes.
cardTransactionAmount Number Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field. Currency. Amount of the charge in the spend currency.
cardTransactionCurrency String ISO 4217 3-letter alpha code. Alphanumeric. Currency code for the spend currency.
cardTransactionID String - Alphanumeric. Calculated value assigned to this card entry during the import process. Maximum length 32 characters.
cardTransactionPostedAmount Number Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field. Currency. Amount of the charge in the billing currency of the card.
cardTransactionPostedCurrency String ISO 4217 3-letter alpha code. Alphanumeric. Currency code for the card billing currency.
cashAdvanceId String - GUUID. Unique system ID assigned to the cash advance. Maximum length 32 characters.
clearingAccountCode String - Alphanumeric. Contains the expense type account code. - or - If a CBCP Personal expense, the company card clearing account code. - or - If charge is tied to a Statement Report, and accounting code is set for Company Billed card account, the card's accounting code as specified in the Account Code field when creating or editing a CBS account. Maximum length 20 characters.
countryCode String ISO 3166-1 alpha-2 country code. Alphanumeric. The report country. Example: United States is US.
countrySubCode String - Alphanumeric. Report entry country sub code. Maximum length 6 characters.
currencyAlphaCode String ISO 4217 3-letter alpha code. Alphanumeric. Currency ISO alpha code for the spend currency if not an imported credit card or the invoice currency if this is a credit card.
currencyNumCode String ISO 4217 3-letter alpha code. Alphanumeric. Currency code for the transaction currency using ISO number code.
employeeCurrencyAlphaCode String ISO 4217 3-letter alpha code. Alphanumeric. Reimbursement currency.
exchangeRate Number - Rate used to convert from the report entry (spend) currency to the report (reimbursement) currency. Maximum length 23 characters.
expensePayIndicator String Y/N Indicates whether Expense Pay reimbursed this journal entry. Either: Y = Expense Pay or N = not Expense Pay.
issuedDate String yyyy-mm-ddThr:min:sec.msZ Date of issue.
isTest String Y/N Signifies if this report belongs to a test user in system.
entrylocationName String - Alphanumeric. The report entry location name (for example, city name). Maximum length 64 characters.
name String - Alphanumeric. Cash advance request name. Maximum length 40 characters.
paymentMethod String 0 = Non-Expense Pay method used for disbursement or 1 = Expense Pay method used for disbursement. Alphanumeric. The method used, either Expense Pay or Other, used for disbursement of the cash advance.
purpose String - Alphanumeric. Describes the purpose of cash advance issued. Maximum length 2,000 characters.
requestAmount Number Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field. Currency. For issue journal record, the total amount of the cash advance in the cash advance transaction currency.
requestDate String yyyy-mm-ddThr:min:sec.msZ Date of cash advance request from the detailed cash advance record.
requestedDisbursementDate String yyyy-mm-ddThr:min:sec.msZ Cash advance disbursement date.
transactionType String 1 = Issue or Return to Administrator, 2 = Application, including Cash Advance Return expense within a report, or 3 = System Cash advance, from balance carry forward. Alphanumeric. Type of transaction.
travelEndDate String yyyy-mm-ddThr:min:sec.msZ The last day of the trip on the assigned travel request itinerary.
travelStartDate String yyyy-mm-ddThr:min:sec.msZ The first day of the trip on the assigned travel request itinerary.

Cash Advance - journalData

Name Type Format Description
accountCode String - Alphanumeric. Contains the expense type account code. - or - If a CBCP Personal expense, the company card clearing account code. - or - If charge is tied to a Statement Report, and accounting code is set for Company Billed card account, the card's accounting code as specified in the Account Code field when creating or editing a CBS account. Maximum length 48 characters.
amount Number Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field. Currency. Value, as credit or debit, of the amount to be exchanged between the payer and payee for this expense account code (not an absolute value) EXAMPLES: Value of zero, credit, or debit, as the following: 0 (Zero) "0," + (Plus / Debit) "+50.00," or - (Minus / Credit) "-50.00."
debitOrCredit String DR/CR Alphanumeric. Either: DR = Debit or CR = credit.
payee String - Alphanumeric. Either a company or an employee depending on the payment type. Maximum length 64 characters.
payer String - Alphanumeric. Either a company or an employee depending on the payment type. Maximum length 64 characters.
paymentCode String - Alphanumeric. The payment code for either a payee or payer. Maximum length 80 characters.

Financial Integration Service Use Cases

Overview

The use case examples below illustrate expense scenarios and the related posting records. Posting records will vary based on app design. The use case documentation is not meant to be a comprehensive list of all use cases and expense scenarios. However, the JSON from the Financial Integration Service will provide all the required data to support the all potential financial use cases.

Simple Expense Posting Without Tax

Simple Out-of-Pocket Cash Expense

Description

Very simple expense report with only a few expense items without VAT, for example, US expense report.

Posting Example

Expense Report with one expense item: Taxi – USD 10

Posting Record

Account Debit Credit
Expense (Taxi) USD 10 -
Employee Vendor - USD 10

Standard Accounting Extract Details

JSON Example

Simple Out-of-Pocket Cash Credit

Description

The user receives a USD 50 cash rebate for a hotel stay that was fully reimbursed on a previous expense report. Being a good corporate citizen the user enters a single USD 50 cash credit transaction and assigns it to the Expense Type "Hotel." The expense is a legitimate business expense, not a personal expense. It is not itemized.

Posting Example

Posting Record

Account Debit Credit
Expense (Hotel) - USD 50
Employee Vendor USD 50 -

Standard Accounting Extract Details

JSON Example

Simple Personal Car Mileage Expense

Description

The user enters a single personal car mileage transaction for a round trip to the airport of 60 miles. The expense is a legitimate business expense, not a personal expense. It is not itemized.

Posting Example

Posting Record

Account Debit Credit
Expense (Mileage) USD 24.30 -
Employee Vendor - USD 24.30

Standard Accounting Extract Details

JSON Example

Travel Allowances – Company Specific Rate Greater Than Government Rate

Description

A German traveler receives meal per diems that are higher the legal rates. In this case he gets EUR 50 instead of the EUR 24 legal amount allowed for a full day. As a result the amount reimbursed to the employee over the legal daily rate is taxable to the employee.

Posting Example

Posting Record

Account Debit Credit
Expense (Meals) EUR 50 -
Employee Vendor (non-taxable) - EUR 24
Employee Vendor (taxable) - EUR 26

Standard Accounting Extract Details

JSON Example

VAT Handling

The SAP Concur system, when configured and applicable, will calculate the related VAT tax for a given transaction. This determination relies on the customer’s tax configuration and will vary by customer and country. The posting document will include all related VAT amounts that are calculated.

How the VAT is handled is determined based on the Tax Code customization in ERP and the related VAT use cases that the partner application supports.

Expense Posting With Single Tax Item

Description

Very simple expense report with only a few expense items with VAT, for example, German expense report.

Posting Example

The posting below is one example of how the expense gets recorded by the customer based on their ERP set up and requirements.

Expense Report with one expense item: Laundry – EUR 10 (including 16 % - EUR 1.60 VAT).

Posting Record

Account Debit Credit
Expense (amount net of tax) EUR 8.40 -
VAT EUR 1.60 -
Employee Vendor (gross amount) - EUR 10

JSON Example

Non-Deductible VAT

The SAP Concur system, when configured and applicable, will calculate the related VAT tax for a given transaction. In some cases, this tax is deductible if it meets certain country-based requirements. In other cases, it is not deductible. This determination relies on the customer’s tax configuration and will vary by customer and country. The posting document will include all related VAT amounts that are calculated.

How the VAT is handled is determined based on the Tax Code customizing in ERP and the related VAT use cases that the partner application supports.

Description

Very simple expense report with only a few expense items with VAT, for example, German expense report.

Posting Example

The posting below is one example of how the expense gets recorded by the customer based on their ERP set up and requirements.

Expense Report with one expense item: Gas – EUR 100 (including 15.97% - EUR 15.97 VAT)

Posting Record

Account Debit Credit
Expense (amount net of tax) EUR 84.03 -
Non-deductible VAT Expense EUR 15.97 -
Employee Vendor (gross amount) - EUR 100

JSON Example

Expense Posting With Multiple Tax Items

Description

For a country like Canada, with multiple tax jurisdictions the entry may have multiple tax lines representing calculated VAT for each jurisdiction. The posting document will include all related tax lines and corresponding tax amounts.

Posting Example

The posting below is one example of how the expense gets recorded by the customer based on their ERP set up and requirements.

Expense Report with one expense item: Local Phone – CAD 100 with multiple tax jurisdictions (for example, tax type 1, tax type 2).

Posting Record

Account Debit Credit
Expense (amount net of tax) 88.50 CAD -
Tax Type 1 CAD 4.42 -
Tax Type 2 CAD 7.08 -
Employee Vendor (gross amount) - CAD 100

JSON Example

Partially Deductible VAT

Description

In some cases it could be possible that the whole VAT amount is not deductible. This case has similar posting options as non-deductible VAT.

Posting Example

The posting below is one example of how the expense gets recorded by the customer based on their ERP set up and requirements.

For a hotel receipt of CAD 55 (including 11.5% - CAD 6.32 VAT) the VAT is only deductible by 50%.

Posting Record

Account Debit Credit
Expense (amount net of tax) CAD 48.68 -
VAT CAD 3.16 -
Non-deductible VAT CAD 3.16 -
Employee Vendor (gross amount) - CAD 55

JSON Example

Foreign Expense Report Without VAT

Description

The SAP Concur system, when configured and applicable, will calculate the related VAT tax for a given transaction. In some cases, this tax is deductible if it meets certain country-based requirements. In other cases, it is not deductible. This determination relies on the customer’s tax configuration and will vary by customer and country. The posting document will include all related VAT amounts that are calculated.

In case an employee from a country with VAT enters a foreign receipt and the included VAT is not claimable, the document has to be posted with a 0% VAT tax code. In SAP Concur this tax code is normally customized for the tax authority in the non-domestic code field. Again, this will vary based on the exact use case and customer’s tax configuration.

Posting Example

A UK employee submits an entry for a US-based training. In this case the posting document will include U.S tax included on the receipt and the posting will be handled in the ERP according to the desired posting record. It’s common that the posting record will include the tax amount as part of the overall expense (in this case Hotel) but a valid tax code with a 0% rate will also be included. This allows the customer to report on foreign taxes paid but which are not reclaimable.

The posting below is one example of how the expense gets recorded by the customer based on their ERP set up and requirements.

Posting Record

Account Debit Credit
Room Rate GBP 60.24 -
Hotel Tax GBP 20.08 -
Card Vendor - GBP 80.32

JSON Example

Itemization

Itemized Expense Items

Description

John flew to New York to meet with a client and stayed one night at the Marriot. An original receipt is split into several parts, for example, lodging costs per night, room tax, and breakfast. All items should be processed separately in the Journal Section, SAE, and JSON.

Posting Example

For a hotel receipt of USD 325 where the costs per night and other expenses should be posted separately.

Posting Record

Account Debit Credit
Room Rate USD 250 -
Room Tax USD 50 -
Breakfast 25 USD -
Employee Vendor - USD 325

Standard Accounting Extract Details

JSON Example

Cost Allocation

What is cost allocation? Allocation is defined as a part of cross-charging is the ability to assign cost of an expense to multiple organizational units such as department, cost center, project code, etc.

When allocating the expense across multiple cost centers, the user needs to pick the correct code from the most granular level which may be from the Expense Entry, Journal Entry, and/or Allocation Entry depending on whether or not the customer is configured to use the allocation fields. Cost center codes should NEVER be picked up from the Employee Entry section because an employee may have to charge another department for a percentage of a transaction.

Expense With Multiple Cost Allocations

Description

Similar to the itemized expense example, however, the breakfast cost is allocated between two different cost centers.

Posting Example

For a hotel receipt of USD 325 where the costs per night and other expenses should be posted separately.

Posting Record

Account Debit Credit
Room Rate USD 250 -
Room Tax USD 50 -
Breakfast 25 USD -
Employee Vendor - USD 325

Extract Details

Standard Accounting Extract Details

JSON Example

NOTE: The room rate and room tax is charged to the same cost center as in the itemized expense example. Only the breakfast cost is allocated 50% between two different cost centers: 0021-Bellevue1 and Top Management. The allocation section is towards the bottom of the JSON.

Cash Advances

Issuance

Description

An employee requests a cash advance to be paid in cash or via transfer.

Posting Example

Employee requests a cash advance of USD 7000 for trip to TechEd.

Posting Record

Account Debit Credit
Cash Advance Clearing Account USD 7000 -
Employee Vendor - USD 7000

Standard Accounting Extract Details

Note: This extract example is the same as Itemized Expense Items.

JSON Example

Application

Cash Advance Is Lower Than the Payout Amount

Description

The employee enters an expense report and assigns a cash advance. This cash advance reduces the employee’s payout amount. Only the difference between the sum of the expense items paid by the employee and the cash advance will be paid to the employee.

Posting Example

The user has requested and received an GBP 300 cash advance. In the course of travel the user incurs the following cash expenses: GBP 245 for a rental car, GBP 60 for a business meal, and GBP 10 for parking. After returning from travel the user finds the GBP 300 cash advance has been issued via the corporate card import process. He assigns the GBP 300 cash advance to an expense report and enters the three cash expenses and submits. The expenses are not itemized. The expenses are legitimate business expenses.

Posting Record

Account Debit Credit
Car Rental GBP 245 -
Meal GBP 60 -
Parking GBP 10 -
Cash Advance Clearing Account GBP 300 -
Employee Vendor - GBP 15

Extract Details

Standard Accounting Extract

JSON Example

Standard Accounting Extract

JSON Example

Cash Advance Is Higher Than the Payout Amount

Description

The employee enters an expense report and assigns a cash advance. If the cash advance is higher than the sum of the expense items paid by the employee the employee owes the difference to the company.

Posting Example

The user has requested and received a GBP 400 cash advance and during travel spends GBP245 on a rental car, GBP 60 on a business meal, and GBP 10 on parking. The user assigns the GBP 400 cash advance to the expense report and enters the three cash expenses and submits. The expenses are not itemized. The expenses are legitimate business expenses. Because the total of the cash advance exceeds the sum of the business expenses the net result of the expense report is that the employee owes the company the balance. The employee will write a check to the company for the balance (GBP 85) and enter a cash advance return transaction in that amount to net the expense report to zero.

Posting Record

Account Debit Credit
Car Rental GBP 245 -
Meals GBP 60 -
Parking GBP 10 -
Cash Advance Clearing Account - GBP 400
Employee Vendor GBP 85 -

Extract Details

Standard Accounting Extract

JSON Example

Standard Accounting Extract

JSON Example

Credit Card Types

Employee Paid Credit Card

Payment via Employee Vendor Account

Description

Credit card items with employee liability should be paid to the employee’s bank account like cash paid expenses. (IBIP)

Posting Example

Expense Report with one employee paid credit card item: Taxi - USD 10.

Posting Record

Account Debit Credit
Expense (Taxi) USD 10 -
Employee Vendor - USD 10

Standard Accounting Extract

JSON Example

Payment via Credit Card Vendor Account (Split Payment)

Description

Approved business expenses should be paid to the credit card instead of the employee’s bank account. (IBCP)

Posting Example

Car rental was paid with IBIP card for USD 56.10.

Posting Record

Account Debit Credit
Expense (Car Rental) USD 56.10 -
Credit Card Vendor - USD 56.10

Standard Accounting Extract

JSON Example

Credit Transaction via Credit Card Vendor Account (Split Payment)

Example

The user receives a USD 349 credit on the corporate card for an unused airline ticket. The credit transaction is displayed as a pre-populated corporate card transaction and the user selects it and submits an expense report. The expense is a legitimate business expense, not a personal expense. It is not itemized.

Posting

Posting Record

Account Debit Credit
Expense (Airfare) - USD 349
Credit Card Vendor USD 349 -

Standard Accounting Extract

JSON Example

Simple IBCP Corporate Card Charge With Itemization

Example

John flew to New York to meet with a client and stayed one night at the Marriot. An original receipt is split into several parts, for example, lodging costs per night, room tax, and breakfast. All items should be processed separately in the Journal Section, SAE, and JSON.

Posting Example

For a hotel receipt of USD 325 where the costs per night and other expenses should be posted separately.

Posting Record

Account Debit Credit
Room Rate USD 250 -
Room Tax USD 50 -
Breakfast USD 25 -
Employee Vendor - USD 325

Standard Accounting Extract

JSON Example

IBCP With Personal Expense: No Out-of-Pocket

NOTE: Personal expenses paid by an IBCP credit card will not be included in the JSON.

Example

John flew to New York to meet with a client and stayed one night at the Marriot. An original receipt is split into several parts, for example, lodging costs per night, room tax, and breakfast. All items should be processed separately in the Journal Section, SAE, and JSON. Since breakfast is a personal expense, it will be included in the extract but NOT in the JSON.

Posting Example

For a hotel receipt of USD 325 where the costs per night and other expenses should be posted separately.

Posting Record

Account Debit Credit
Room Rate USD 250 -
Room Tax USD 50 -
Breakfast (personal) USD 25 -
Employee Vendor - USD 325

Standard Accounting Extract

JSON Example

IBCP with Personal Expense Where Out-of-Pocket Exceeds the Personal Expense

NOTE: Personal expenses paid by an IBCP credit card will not be included in the JSON when a non-offsetting payment is used because it’s not relevant to the company’s accounting record.

Without Offsetting

Example

The user assigns a pre-populated corporate card transaction to the expense report. The transaction is a Hotel expense in the amount of USD 284. The hotel expense consists of a two-night stay at USD 125 per night and the user had a USD 20 dinner after checking in and ordered an in-room movie for USD 14 that the company does not reimburse for. The expense is itemized. The expense is a legitimate business expense with the exception of the in-room movie that the user marks as a non-reimbursable expense on the expense report. The expense report also includes an out-of-pocket cash transaction for a taxi at USD 35.

Posting

Posting Record

Account Debit Credit
Room Rate USD 125 -
Room Rate USD 125 -
Dinner USD 20 -
Taxi USD 35 -
Credit Card Vendor - USD 270
Employee Vendor - USD 35

JSON Example

With Offsetting

When using offsets the amount due the employee for out-of-pocket expenses is netted (or offset) against the amount marked as personal, resulting in an entry reflecting either the final amount the employee owes the company (assumes personal exceeds out of pocket) or final amount company owes the employee (reduced by any personal amounts).

Posting

Posting Record

Account Debit Credit
Room Rate USD 125 -
Room Rate USD 125 -
Dinner USD 20 -
Taxi USD 14 -
Taxi USD 21 -
Credit Card Vendor - USD 284
Employee Vendor - USD 21

Extract Details

Standard Accounting Extract

JSON Example

IBCP With Personal Expense Where Out-of-Pocket Is Less Than Personal Expense

NOTE: Personal expenses paid by an IBCP credit card will not be included in the JSON when a non-offsetting payment is used because it’s not relevant to the company’s accounting record.

Without Offsetting

Example

The user assigns a pre-populated corporate card transaction to the expense report. The transaction is a Hotel expense in the amount of USD 284. The hotel expense consists of a two-night stay at USD 125 per night and the user had a USD 20 dinner after checking in and ordered an in-room movie for USD 14 that the company does not reimburse for. The expense is itemized. The expense is a legitimate business expense with the exception of the in-room movie that the user marks as a non-reimbursable expense on the expense report. The expense report also includes an out-of-pocket cash transaction for parking in the amount of USD 5.

Posting

Posting Record

Account Debit Credit
Hotel USD 125 -
Hotel USD 125 -
Dinner USD 20 -
Parking USD 5 -
Credit Card Vendor - USD 275

JSON Example

With Offsetting

When using offsets the amount due the employee for out-of-pocket expenses is netted (or offset) against the amount marked as personal, resulting in an entry reflecting either the final amount the employee owes the company (assumes personal exceeds out of pocket) or final amount company owes the employee (reduced by any personal amounts).

Posting

Posting Record

Account Debit Credit
Hotel USD 125 -
Hotel USD 125 -
Dinner USD 20 -
Parking USD 5 -
Credit Card Vendor - USD 275

Standard Accounting Extract

JSON Example

Company Paid Credit Card

CBCP Corporate Card Charge for Entirely Personal Expense (Net Due Company With Consolidated or Verbose Extract)

Example

The employee mistakenly uses the corporate card to pay for tolls (USD 32) and dues (USD 49) expense totaling USD 81. When the corporate card transaction feed populates the company card page the employee must deal with this transaction. The employee assigns the USD 81 corporate card transaction to an expense report, marks it as a non-reimbursable expense and submits the report for approval.

Posting

Posting Record

Account Debit Credit
Employee Vendor USD 49 -
Credit Card Clearing - USD 49
Credit Card Clearing USD 49 -
Credit Card Vendor - USD 49
Employee Vendor USD 32 -
Credit Card Clearing - USD 32
Credit Card Clearing USD 32 -
Credit Card Vendor - USD 32

Standard Accounting Extract

JSON Example

CBCP Corporate Card Charge with Itemization and Personal Expense (Net Due Employee With Consolidation)

Example

The user assigns a pre-populated corporate card transaction to the expense report. The transaction is a Hotel expense in the amount of USD 284. The hotel expense consists of a two-night stay at USD 125 per night and the user had a USD 20 dinner after checking in and ordered an in-room movie for USD 14 that the company does not reimburse for. The expense is itemized. The expense is a legitimate business expense with the exception of the in-room movie that the user marks as a non-reimbursable expense on the expense report. The expense report also includes an out-of-pocket cash transaction for a taxi at USD 35.

Posting

Posting Record

Expense Report:

Account Debit Credit
Room Rate USD 125 -
Room Rate USD 125 -
Dinner USD 20 -
Taxi USD 32 -
Employee Vendor (personal expense) USD 14 -
Employee Vendor - USD 35
Credit Card Clearing - USD 284

Standard Accounting Extract

JSON Example

CBCP Corporate Card Charge for Entirely Personal Expense (Net Due Company With Verbose Extract)

Example

The employee mistakenly uses the corporate card to pay for a personal dinner expense of USD 300. When the corporate card transaction feed populates the company card page the employee must deal with this transaction. The employee assigns the USD 300 corporate card transaction to an expense report, marks it as a non-reimbursable expense and submits the report for approval.

Posting

Posting Record

Account Debit Credit
Employee Vendor USD 300 -
Credit Card Clearing Account - USD 300
Credit Card Clearing Account USD 300 -
Credit Card Vendor - USD 300

Standard Accounting Extract

JSON Example

CBCP Corporate Card Charge with Itemization and Personal Expense (Net Due Employee With No Offsets)

Example

The user assigns a pre-populated corporate card transaction to the expense report. The transaction is a Hotel expense in the amount of USD 284. The hotel expense consists of a two-night stay at USD 125 per night and the user had a USD 20 dinner after checking in and ordered an in-room movie for USD 14 that the company does not reimburse for. The expense is itemized. The expense is a legitimate business expense with the exception of the in-room movie that the user marks as a non-reimbursable expense on the expense report. The expense report also includes an out-of-pocket cash transaction for a taxi at USD 35.

Posting

Posting Record

Account Debit Credit
Room Rate USD 125 -
Room Rate USD 125 -
Dinner USD 20 -
Taxi USD 35 -
Employee Vendor (out of pocket) - USD 35
Employee Vendor (personal expense) USD 14 -
Credit Card Vendor - USD 284

Standard Accounting Extract

JSON Example

Financial Integration Use Cases Extract Information

Note: The extract file excerpts in this document are a reference point for those developers who have used those files for prior financial integrations. This excerpt is intended to help those developers transition from an extract file to the Financial Integration Service. This allows you to identify what you have been using from the extract file and to locate the same data in the new JSON response. If you have not used the extract file previously, the extract file excerpts can be skipped.

Simple Expense Posting Without Tax

Simple Out-of-Pocket Cash Expense

The Payer in this instance is the company; the Payee is the employee. Since it is not an itemized expense the Entry Transaction Type is REG. Because it is a legitimate business expense the ‘Is Personal’ flag is set to ‘N’. The employee will be reimbursed for this transaction.

[61] entry_id [64] Entry Transaction Date [70] Vendor Name [63] Expense Type [68] Is Personal [62] Entry Transaction Type [163] Payer Payment Type [165] Payee Payment Type [169] Journal Amount [168] Debit Credit [167] Account Code [177] Cash Advance Amount [185] Cash Advance Transaction Type
8337 03/05/2016 - Taxi N REG COMPANY EMPLOYEE USD 10 DR 474230 - -

Simple Out-of-Pocket Cash Credit

The Payer in this instance is the employee; the Payee is the company. Since it is not an itemized expense the Entry Transaction Type is REG. Because it is a legitimate business expense the ‘Is Personal’ flag is set to ‘N’. The company will be reimbursed for this transaction.

[61] entry_id [64] Entry Transaction Date [70] Vendor Name [63] Expense Type [68] Is Personal [62] Entry Transaction Type [163] Payer Payment Type [165] Payee Payment Type [169] Journal Amount [168] Debit Credit [167] Account Code [177] Cash Advance Amount [185] Cash Advance Transaction Type
4178 5/28/2019 Ritz Carlton Booking Fees (Hotel) N REG EMPLOYEE COMPANY USD -50 CR 5 - -

Simple Personal Car Mileage Expense

The Payer in this instance is the company; the Payee is the employee. Since it is not an itemized expense the Entry Transaction Type is REG. Because it is a legitimate business expense the ‘Is Personal’ flag is set to ‘N’. The employee will be reimbursed for this transaction.

[61] entry_id [64] Entry Transaction Date [70] Vendor Name [63] Expense Type [68] Is Personal [62] Entry Transaction Type [163] Payer Payment Type [165] Payee Payment Type [169] Journal Amount [168] Debit Credit [167] Account Code [177] Cash Advance Amount [185] Cash Advance Transaction Type
4173 5/23/2019 - Mileage N REG COMPANY EMPLOYEE USD 24.30 DR 54 - -

Travel Allowances: Company Specific Rate Greater Than Government Rate

The Payer in this instance is the company; the Payee is the employee. Since it is not an itemized expense the Entry Transaction Type is REG. Because it is a legitimate business expense the ‘Is Personal’ flag is set to ‘N’. The employee will be reimbursed for this transaction.

The report entry item will be split into 2 journal entry items: 1st item: amount up to the legal limit, 2nd item: amount above the legal limit.

[61] entry_id [64] Entry Transaction Date [70] Vendor Name [63] Expense Type [68] Is Personal [62] Entry Transaction Type [163] Payer Payment Type [165] Payee Payment Type [169] Journal Amount [168] Debit Credit [167] Account Code [177] Cash Advance Amount [185] Cash Advance Transaction Type
4196 5/28/2019 - Fixed Meals N REG COMPANY EMPLOYEE 24 EUR DR 474230 - -
4197 5/28/2019 - Fixed Meals N REG COMPANY EMPLOYEE 26 EUR DR 474230 - -

VAT Handling

Expense Posting With Single Tax Item

For the expense line: The Payer in this instance is the company; the Payee is the employee. Since it is not an itemized expense the Entry Transaction Type is REG. Because it is a legitimate business expense the ‘Is Personal’ flag is set to ‘N’. The employee will be reimbursed for this transaction. The Tax Code will also appear on this detail line along with the Tax Authority details (label and name).

Tax data: The appearance of the tax data in the extract is governed by the extract options to either include tax information in the same detail line as the entry on which tax is calculated, or to include it as a separate journal line. In this example tax is set to appear as a journal line. The payer is the notional tax authority with the payee as the company (as the reclaimed tax will eventually be paid by the tax authority to the company).

The Journal Amount on the tax detail line can be set to either list the amount eligible to reclaim on either the posted or adjusted (reclaim_posted_amount or reclaim_adjusted_amount). If ‘Adjusted’ the tax reclaim will be calculated on the approved amount (the approved amount may be lower than the claimed (posted) amount). The Tax Source identifies the source of the tax calculation.

The Tax Code can also be set to appear in the Account Code field on the tax detail line (instead of the account code), as shown in this example. The difference between the ‘reclaim’ fields (reclaim_tax_amount, reclaim_posted_amount, reclaim_adjusted_amount) and other tax amount fields (tax_amount, tax_posted_amount, etc.) is that ‘Reclaim’ indicates that these figures are subject to the reclaim percentage specified in the tax configuration.

[61] entry_id [64] Entry Transaction Date [63] Expense Type [68] Is Personal [62] Entry Transaction Type [163] Payer Payment Type [165] Payee Payment Type [169] Journal Amount [168] Debit Credit [167] Account Code [226] Tax Auth Label [227] Tax Amount [228] Tax Posted Amount [229] Tax Source [230] reclaim_tax_amount [231] reclaim_posted_amount [232] Tax Code [233] reclaim_domestic
4282 6/5/2019 Laundry N REG EMPLOYEE COMPANY 8.40 EUR DR 37 ILR 0 0 - 0 0 V1 -
4282 6/5/2019 Laundry N REG ILR COMPANY 1.60 EUR CR V1 ILR 1.60 1.60 SYST 1.60 1.60 V1 Y

Itemization

Itemized Expense Items

The Payer in this instance is the company; the Payee is the corporate card vendor. Since it is an itemized expense the Entry Transaction Type is CHD. Because it is a legitimate business expense the ‘Is Personal’ flag is set to ‘N’. Because this is an IBCP transaction and the payment will be made to the card vendor on behalf of the employee the employee will not receive reimbursement.

[61] entry_id [64] Entry Transaction Date [70] Vendor Name [63] Expense Type [68] Is Personal [62] Entry Transaction Type [163] Payer Payment Type [165] Payee Payment Type [169] Journal Amount [168] Debit Credit [167] Account Code [177] Cash Advance Amount [185] Cash Advance Transaction Type
4199 05/27/2019 All Suites International Hotel Room Rate N CHD COMPANY IBCP CORP USD 250 DR 474230 - -
4200 05/27/2019 All Suites International Hotel Tax N CHD COMPANY IBCP CORP USD 50 DR 474230 - -
4201 05/28/2019 All Suites International Breakfast N CHD COMPANY IBCP CORP USD 25 DR 474230 - -

Cash Advances

Issuance Extract (For reference only. Issuance is not included in the Expense Report FI Document)

There will be one issuance record for each cash advance issued. The issuance record can be identified by the Cash Advance Transaction Type which will always be a ‘1’. The Payer is the Company and the Payee is the Employee. The Journal Amount is a DR transaction in the reimbursement currency. The Cash Advance Amount is the amount of the cash advance in the currency of issuance. The Account Code is the employee cash advance account code, which is an element of the employee profile.

[61] entry_id [64] Entry Transaction Date [70] Vendor Name [63] Expense Type [68] Is Personal [62] Entry Transaction Type [163] Payer Payment Type [165] Payee Payment Type [169] Journal Amount [168] Debit Credit [167] Account Code [177] Cash Advance Amount [185] Cash Advance Transaction Type
- 3/7/2019 - - N - COMPANY EMPLOYEE USD 7000 DR 1009990 USD 7000 1

Cash Advance Is Lower Than the Payout Amount

Issuance Extract (For reference only. Issuance is not included in the Expense Report FI Document)

There will be one issuance record for each cash advance issued. The issuance record can be identified by the Cash Advance Transaction Type which will always be a ‘1’. The Payer is the Company and the Payee is the Employee. The Journal Amount is a DR transaction in the reimbursement currency. The Cash Advance Amount is the amount of the cash advance in the currency of issuance. The Account Code is the employee cash advance account code, which is an element of the employee profile.

[61] entry_id [64] Entry Transaction Date [70] Vendor Name [63] Expense Type [68] Is Personal [62] Entry Transaction Type [163] Payer Payment Type [165] Payee Payment Type [169] Journal Amount [168] Debit Credit [167] Account Code [177] Cash Advance Amount [185] Cash Advance Transaction Type
- 6/22/2019 - - N - COMPANY EMPLOYEE GBP 300 DR - GBP 300 1

The application of the CA issuance:

The application phase of this case will spawn five records in the standard extract file. Three of the records will cover the three cash out-of-pocket transactions. These three transactions are handled in the same way all cash, out-of-pocket transactions are handled (See the posting record above).

The two additional records are unique to an expense report containing a cash advance. The system will attempt to recover the cash advance amount from the employee by creating credit records against the cash transactions until the total of the cash advance is recovered. In this example, the first cash advance record (entry_id 61) credits the entire GBP 245 of its companion record (entry_id 58). That still leaves GBP 55 of the cash advance unrecovered. So another credit record (entry_id 62) in the amount of GBP 55 will be created against the next companion cash expense record (entry_id 59 and 60). At this point the GBP 300 cash advance has been recovered. The credit journal amounts have the effect of offsetting the total amount due the employee by the amount of the cash advance.

These offset records will have the following characteristics: the Payer is the employee; the Payee is the company. The debit/credit indicator will always be ‘CR’. The Cash Advance Amount field will always contain the total of the cash advances applied to the expense report. The Cash Advance Transaction Type will be a ‘2’. The employee will receive the net of the total cash expenses less the cash advance amount; in this example, GBP 15.

[61] entry_id [64] Entry Transaction Date [70] Vendor Name [63] Expense Type [68] Is Personal [62] Entry Transaction Type [163] Payer Payment Type [165] Payee Payment Type [169] Journal Amount [168] Debit Credit [167] Account Code [177] Cash Advance Amount [185] Cash Advance Transaction Type
58 6/21/2019 null Rental Car N REG COMPANY EMPLOYEE GBP 245 DR 109 - -
59 6/21/2019 Qdoba Dinner N REG COMPANY EMPLOYEE GBP 60 DR 105 - -
60 6/21/2019 Republic Parking Parking N REG COMPANY EMPLOYEE GBP 10 DR 130 - -
61 6/21/2019 - Rental Car N REG EMPLOYEE COMPANY GBP -245 CR 1009990 GBP 300 2
62 6/21/2019 - Dinner & Parking N REG EMPLOYEE COMPANY GBP -55 CR 1009990 GBP 300 2

Cash Advance Is Higher Than the Payout Amount

Issuance Extract (For reference only. Issuance is not included in the Expense Report FI Document)

There will be one issuance record for each cash advance issued. The issuance record can be identified by the Cash Advance Transaction Type which will always be a ‘1’. The Payer is the company and the Payee is the employee. The Journal Amount is a DR transaction in the reimbursement currency. The Cash Advance Amount is the amount of the cash advance in the currency of issuance. The Account Code is the employee cash advance account code, which is an element of the employee profile.

[61] entry_id [64] Entry Transaction Date [70] Vendor Name [63] Expense Type [68] Is Personal [62] Entry Transaction Type [163] Payer Payment Type [165] Payee Payment Type [169] Journal Amount [168] Debit Credit [167] Account Code [177] Cash Advance Amount [185] Cash Advance Transaction Type
- 6/22/2019 - - N - COMPANY EMPLOYEE GBP 400 DR - GBP 300 1

The application of the CA issuance:

The application phase of this case will spawn seven records in the standard extract file. Three of the records will cover the three cash out-of-pocket transactions. These three transactions are handled in the same way all cash, out-of-pocket transactions are handled (See the posting record above).

The four additional records are unique to an expense report containing a cash advance. The system will attempt to recover the cash advance amount from the employee by creating credit records against the cash transactions until the total of the cash advance is recovered. In this example, since the total of all expenses does not equal or exceed the cash advance amount, all three expense records have a corresponding offset credit. That still leaves the user GBP 85 short. The cash advance return record in the amount of a GBP 85 credit nets the cash advance amount to zero.

These offset records will have the following characteristics: the Payer is the employee; the Payee is the company. The debit/credit indicator will always be ‘CR’. The Cash Advance Amount field will always contain the total of the cash advances applied to the expense report. The Cash Advance Transaction Type will be a ‘2’. The employee will receive the net of the total cash expenses less the cash advance amount and in the case of a net due to company the employee will be required to submit a cash advance return to retire the balance owed; in this example, GBP 85.

[61] entry_id [64] Entry Transaction Date [70] Vendor Name [63] Expense Type [68] Is Personal [62] Entry Transaction Type [163] Payer Payment Type [165] Payee Payment Type [169] Journal Amount [168] Debit Credit [167] Account Code [177] Cash Advance Amount [185] Cash Advance Transaction Type
61 6/21/2019 AVIS Rental Car N REG COMPANY EMPLOYEE GBP 245 DR 109 - -
62 6/21/2019 MORTONS Business Meal N REG COMPANY EMPLOYEE GBP 60 DR 105 - -
63 6/21/2019 Republic Parking Parking N REG COMPANY EMPLOYEE GBP 10 DR 130 - -
- 6/21/2019 AVIS Rental Car N REG EMPLOYEE COMPANY GBP -245 CR 1009990 GBP 400 2
- 6/21/2019 MORTONS Business Meal N REG EMPLOYEE COMPANY GBP -60 CR 1009990 GBP 400 2
- 6/21/2019 Republic Parking Parking N REG EMPLOYEE COMPANY GBP -10 CR 1009990 GBP 400 2
- 6/21/2019 - Cash Advance Return N REG EMPLOYEE COMPANY GBP -85 CR 1009990 GBP 400 2

Credit Card Types

Payment via Employee Vendor Account

The Payer in this instance is the company; the Payee is the employee. Since it is not an itemized expense the Entry Transaction Type is REG. Because it is a legitimate business expense the ‘Is Personal’ flag is set to ‘N’. The employee will be reimbursed for this transaction.

[61] entry_id [64] Entry Transaction Date [70] Vendor Name [63] Expense Type [68] Is Personal [62] Entry Transaction Type [163] Payer Payment Type [165] Payee Payment Type [169] Journal Amount [168] Debit Credit [167] Account Code [177] Cash Advance Amount [185] Cash Advance Transaction Type
8337 03/05/2016 - Taxi N REG COMPANY EMPLOYEE USD 10 DR 474230 - -

Payment via Credit Card Vendor Account (Split Payment)

The Payer in this instance is the company; the Payee is the corporate card vendor. Since it is not an itemized expense the Entry Transaction Type is REG. Because it is a legitimate business expense the ‘Is Personal’ flag is set to ‘N’. Because this is an IBCP transaction and the payment will be made to the card vendor on behalf of the employee the employee will not receive reimbursement.

[61] entry_id [64] Entry Transaction Date [70] Vendor Name [63] Expense Type [68] Is Personal [62] Entry Transaction Type [163] Payer Payment Type [165] Payee Payment Type [169] Journal Amount [168] Debit Credit [167] Account Code [177] Cash Advance Amount [185] Cash Advance Transaction Type
36 4/7/2008 DOLLAR Rental Car N REG COMPANY IBCP CORP USD 56.10 DR 11 - -

Credit Transaction via Credit Card Vendor Account (Split Payment)

The Payer in this instance is the corporate card vendor; the Payee is the company. Since it is not an itemized expense the Entry Transaction Type is REG. Because it is a legitimate business expense the ‘Is Personal’ flag is set to ‘N’. Because this is an IBCP transaction and the payment/credit will be made to the card vendor on behalf of the employee the employee will not receive reimbursement (or be required to pay the balance).

[61] entry_id [64] Entry Transaction Date [70] Vendor Name [63] Expense Type [68] Is Personal [62] Entry Transaction Type [163] Payer Payment Type [165] Payee Payment Type [169] Journal Amount [168] Debit Credit [167] Account Code [177] Cash Advance Amount [185] Cash Advance Transaction Type
4225 5/27/2019 ALASKA AIRLINE Airfare N REG COPD COMPANY USD -349 CR 474230 - -

Simple IBCP Corporate Card Charge With Itemization

The Payer in this instance is the company; the Payee is the corporate card vendor. Since it is an itemized expense the Entry Transaction Type is ‘CHD’. Because it is a legitimate business expense the ‘Is Personal’ flag is set to ‘N’. Because this is an IBCP transaction and the payment will be made to the card vendor on behalf of the employee the employee will not receive reimbursement.

[61] entry_id [64] Entry Transaction Date [70] Vendor Name [63] Expense Type [68] Is Personal [62] Entry Transaction Type [163] Payer Payment Type [165] Payee Payment Type [169] Journal Amount [168] Debit Credit [167] Account Code [177] Cash Advance Amount [185] Cash Advance Transaction Type
4199 05/27/2019 All Suites International Hotel Room Rate N CHD COMPANY IBCP CORP USD 250 DR 474230 - -
4200 05/27/2019 All Suites International Hotel Tax N CHD COMPANY IBCP CORP USD 50 DR 474230 - -
4201 05/28/2019 All Suites International Breakfast N CHD COMPANY IBCP CORP USD 25 DR 474230 - -

IBCP With Personal Expense: No Out-of-Pocket

The Payer in this instance is the company; the Payee is the corporate card vendor. Since it is an itemized expense the Entry Transaction Type is CHD. Because this is an IBCP transaction and the payment will be made to the card vendor on behalf of the employee the employee will not receive reimbursement. Because the entry marked as personal is not a legitimate/approved business expense, payment to the card vendor is the responsibility of the employee. The amount is not reimbursable to the employee and the expense amount should not be posted with other business transactions. Therefore, the personal amount is not included in the financial posting JSON.

[61] entry_id [64] Entry Transaction Date [70] Vendor Name [63] Expense Type [68] Is Personal [62] Entry Transaction Type [163] Payer Payment Type [165] Payee Payment Type [169] Journal Amount [168] Debit Credit [167] Account Code [177] Cash Advance Amount [185] Cash Advance Transaction Type
4220 05/29/2019 All Suites International Hotel Room Rate N CHD COMPANY IBCP USD 250 DR 474230 - -
4221 05/29/2019 All Suites International Hotel Tax N CHD COMPANY IBCP USD 50 DR 474230 - -
4222 05/30/2019 All Suites International Breakfast Y REG EMPL COMPANY USD 25 DR 199999 - -

IBCP with Personal Expense Where Out-of-Pocket Exceeds the Personal Expense

The Payer for both transactions is the company. The Payee is the corporate card vendor for the legitimate business expenses on the hotel transaction (the hotel expenses and the dinner expense). Because the reimbursement method is IBCP w/offsets, the card vendor will also be the payee for the personal expenses on the hotel transaction up to the total amount of out-of-pocket cash expense submitted on this expense report. Since the non-reimbursable in-room movie expense (USD 14) is less than the total out-of-pocket cash expenses (USD 35) owed to the employee, the company will pay the USD 14 personal expense to the card vendor and offset that amount against the USD 35 owed to the employee. Thus the employee will only receive USD 21 of the USD 35 taxi expense. In this case there were enough out-of-pocket cash expenses to offset the non-reimbursable expenses so there is a net due to the employee for this expense report.

[61] entry_id [64] Entry Transaction Date [70] Vendor Name [63] Expense Type [68] Is Personal [62] Entry Transaction Type [163] Payer Payment Type [165] Payee Payment Type [169] Journal Amount [168] Debit Credit [167] Account Code [177] Cash Advance Amount [185] Cash Advance Transaction Type
89 7/15/2019 MARRIOTT Hotel N CHD COMPANY IBCP CORP USD 125 DR 99999 - -
90 7/16/2019 MARRIOTT Hotel N CHD COMPANY IBCP CORP USD 125 DR 99999 - -
91 7/15/2019 MARRIOTT Dinner N CHD COMPANY IBCP CORP USD 20 DR 600 - -
93 7/16/2019 Taxi Local Trans N REG COMPANY EMPLOYEE USD 21 DR 88888 - -
93 7/16/2019 Taxi Local Trans N REG COMPANY IBCP CORP USD 14 DR 88888 - -

IBCP With Personal Expense Where Out-of-Pocket Is Less Than Personal Expense

The Payer for both transactions is the company. The Payee is the corporate card vendor for the legitimate business expenses on the Hotel transaction (the Hotel expenses and the Dinner expense). Because the reimbursement method is IBCP w/offsets, the card vendor will also be the payee for the personal expenses on the Hotel transaction up to the total amount of out-of-pocket cash expense submitted on this expense report. Since the non-reimbursable in-room movie expense (USD 14) is greater than the total out-of-pocket cash expenses (USD 5) owed to the employee, the company will pay only USD 5 of the USD 14 personal expense to the card vendor and offset that amount against the USD 5 owed to the employee. Thus the employee will not receive any reimbursement and will personally owe the card vendor for the difference between the USD 5 paid by the company on his behalf and the USD 14 charge, or USD 9. In this case there were not enough out-of-pocket cash expenses to offset the non-reimbursable expenses so the employee is responsible to make up the difference with the card vendor.

[61] entry_id [64] Entry Transaction Date [70] Vendor Name [63] Expense Type [68] Is Personal [62] Entry Transaction Type [163] Payer Payment Type [165] Payee Payment Type [169] Journal Amount [168] Debit Credit [167] Account Code [177] Cash Advance Amount [185] Cash Advance Transaction Type
95 7/15/2019 MARRIOTT Hotel N CHD COMPANY IBCP CORP USD 125 DR 99999 - -
98 7/16/2019 MARRIOTT Hotel N CHD COMPANY IBCP CORP USD 125 DR 99999 - -
96 7/16/2019 MARRIOTT Dinner N CHD COMPANY IBCP CORP USD 20 DR 600 - -
99 7/16/2019 PARKING Parking N REG COMPANY IBCP CORP USD 5 DR 40 - -

CBCP Corporate Card Charge for Entirely Personal Expense (Net Due Company With Consolidated or Verbose Extract)

The extract produces two records for this single transaction. One record addresses payment that must be made to the card vendor by the company. The Payer is the company. The Payee is the corporate card vendor. The amount is a debit of USD 49 to the clearing account. Since there are no employee out-of-pocket expenses on this expense report there is nothing to offset the amount that the employee owes the company. Therefore, a separate record is created to address the net due company condition. In this record the Payer is the employee and the Payee is the company. The amount is a credit of USD 49 to the clearing account. The company’s financial system must have a process for dealing with this employee receivable condition. The CT&E system will not “carry over” this net due company amount to subsequent expense reports.

The company will pay the credit card vendor for the full amount due the card and retain a corresponding employee receivable (most likely represented as a debit in the employee’s vendor account. This allows natural offsetting to occur if there are subsequent amounts due the employee posted to their vendor record in the future.

[61] entry_id [64] Entry Transaction Date [70] Vendor Name [63] Expense Type [68] Is Personal [62] Entry Transaction Type [163] Payer Payment Type [165] Payee Payment Type [169] Journal Amount [168] Debit Credit [167] Account Code [177] Cash Advance Amount [185] Cash Advance Transaction Type
- 6/1/2016 - Dues Y REG EMPLOYEE COMPANY USD -49 CR cbcp180 - -
- 6/1/2016 - Dues Y REG COMPANY CBCP CORP USD 49 DR cbcp180 - -
- 6/1/2016 - Tolls Y REG EMPLOYEE COMPANY USD -32 CR compaid374 - -
- 6/1/2016 - Tolls Y REG COMPANY CBCP CORP USD 32 DR compaid374 - -

CBCP Corporate Card Charge with Itemization and Personal Expense (Net Due Employee With Consolidation)

The Payer for both transactions is the company. The Payee is the corporate card vendor for the full amount of the hotel transaction (the company owes the card vendor for the entire amount of the transaction, including the non-reimbursable in-room movie) and the employee for the balance of the taxi expense after the offset is taken for the in-room movie portion of the corporate card transaction. The employee would normally be reimbursed for the full USD 35 out-of-pocket taxi expense but, because a portion of the company paid corporate card transaction was not a legitimate business expense, the system reduces the amount due to the employee by the amount of the non-reimbursable expense. In this case there was enough out-of-pocket cash expenses to offset the non-reimbursable expenses so there is a net due to the employee for this expense report.

[61] entry_id [64] Entry Transaction Date [70] Vendor Name [63] Expense Type [68] Is Personal [62] Entry Transaction Type [163] Payer Payment Type [165] Payee Payment Type [169] Journal Amount [168] Debit Credit [167] Account Code [177] Cash Advance Amount [185] Cash Advance Transaction Type
4252 6/4/2019 MARRIOTT Hotel N CHD COMPANY CBCP CORP USD 125 DR 474230 - -
4253 6/3/2019 MARRIOTT Hotel N CHD COMPANY CBCP CORP USD 125 DR 7271001 - -
4254 6/3/2019 MARRIOTT Dinner N CHD COMPANY CBCP CORP USD 20 DR 474230 - -
4291 5/29/2019 Taxi Local Trans N REG COMPANY EMPLOYEE USD 35 DR 474230 - -
4255 6/5/2019 MARRIOTT In-room movie Y REG COMPANY CBCP CORP USD 14 DR 199999 - -

CBCP Corporate Card Charge for Entirely Personal Expense (Net Due Company With Verbose Extract)

The extract produces two records for this single transaction. One record addresses payment that must be made to the card vendor by the company. The Payer is the company. The Payee is the corporate card vendor. The amount is a debit of USD 300 to the clearing account. The second record is created to address the net due company condition. In this record the Payer is the employee and the Payee is the company. The amount is a credit of USD 300 to the clearing account. The company’s financial system must have a process for dealing with this employee receivable condition. The CT&E system will not “carry over” this net due company amount to subsequent expense reports.

[61] entry_id [64] Entry Transaction Date [70] Vendor Name [63] Expense Type [68] Is Personal [62] Entry Transaction Type [163] Payer Payment Type [165] Payee Payment Type [169] Journal Amount [168] Debit Credit [167] Account Code [177] Cash Advance Amount [185] Cash Advance Transaction Type
- 9/1/2016 Cheesecake Factory Dinner Y REG EMPLOYEE COMPANY USD -300 CR - - -
- 9/1/2016 Cheesecake Factory Dinner Y REG COMPANY CBCP CORP USD 300 DR - - -

CBCP Corporate Card Charge with Itemization and Personal Expense (Net Due Employee With No Offsets)

The records are slightly different from the previous example where offsets are built into the extract. In this case, where there are no built-in offsets, each record is distinct and the offset will need to be calculated in the client’s bridge program. The Payer for both transactions is the company except for the personal portion of the Hotel expense. The personal amount of USD 14 is represented with two distinct records. One record addresses the amount due to the corporate card vendor to ensure that the full amount of the otel transaction (including the personal amount) is paid to the card vendor. A second offsetting record addresses the same personal amount that the employee owes back to the company. In the first record, the company is the Payer and the Payee is the corporate card vendor for the USD 14 non-reimbursable in-room movie). In the second record the employee is the Payer and the Payee is the company for the credit amount of the USD 14 non-reimbursable in-room movie. The full USD 35 out-of-pocket taxi expense is handled as a normal out-of-pocket cash expense with the company being the Payer and the employee being the Payee. The client’s bridge program will need to summarize the two records (+USD 35 taxi and -USD 14 in-room movie) to arrive at the USD 21 due to the employee.

[61] entry_id [64] Entry Transaction Date [70] Vendor Name [63] Expense Type [68] Is Personal [62] Entry Transaction Type [163] Payer Payment Type [165] Payee Payment Type [169] Journal Amount [168] Debit Credit [167] Account Code [177] Cash Advance Amount [185] Cash Advance Transaction Type
4336 6/6/2019 MARRIOTT Hotel N CHD COMPANY CBCP CORP USD 125 DR 474230 - -
4337 6/7/2019 MARRIOTT Hotel N CHD COMPANY CBCP CORP USD 125 DR 474230 - -
4338 6/8/2019 MARRIOTT Dinner N CHD COMPANY CBCP CORP USD 20 DR 474230 - -
4339 6/8/2019 MARRIOTT In-Room Movie Y CHD COMPANY CBCP CORP USD 14 DR 199999 - -
4339 6/8/2019 MARRIOTT In-Room Movie Y CHD EMPLOYEE COMPANY USD 14 CR 199999 - -
4340 6/8/2019 Taxi Local Trans N REG COMPANY EMPLOYEE USD 35 DR 474230 - -

Financial Integration Service v4 - Getting Started

The Financial Integration API allows an external system to interact with financial documents generated from SAP Concur, for financial posting into an ERP.

This API provides an automated solution to request available data objects such as approved expense reports, cash advances, and invoices to import to the client internal system, with an opportunity to send posting confirmation back into SAP Concur before the object is locked down and cannot be altered in SAP Concur.

Below are some benefits for using the Financial Integration service:

Limitations: This API is available to both customers and partners who have been granted access by SAP Concur. Invoice Standard customers should reach out to their SAP Concur representative to receive more information on implementation. Access to this documentation does not provide access to the API. The API is available in North America, EMEA, and China Production and Implementation environments.

Getting Started

Products and Editions

Scope Usage

Name Description Endpoint
FISVC Read financial transactions and write financial transaction acknowledgements and confirmations. GET, POST

Access Token Usage

This API only supports company-level access tokens.

Get Financial Transactions

The request returns a list of financial documents that are ready to be processed. The request can include parameters to limit the results.

Scopes

FISVC - Refer to Scope Usage for full details.

Request

URI

Template
https://{datacenterURI}/financialintegration/fi/v4/companies/transactiontypes/{docType}/transactions
Parameters
Name Type Format Description
docType string path Required The financial document type to return. Only one type of transaction can be retrieved at a time. Supported values are: expense, invoice, cashadvance, payroll, obligation.
page int32 query Starting page number.
limit int32 query Number of records to return per page. Default: 25.
docId string query The transaction unique identifier, it could be expense report ID, payment request ID or cash advance ID. If specified, a single document that matches docId is returned.
ignoreDocumentStatus string query Ignores the financial documents status. If yes, a document is returned regardless of status. If no, only documents that have not been acknowledged/confirmed are returned. Supported values: yes, no. (See note below)
systemId string query The external system ID that processed the document. Maximum 50 characters.

Note The ignoreDocumentStatus parameter is useful for Universal (Standard Edition) customers who are using a Test ERP with a production SAP Concur expense report (Universal customers don't have SAP Concur test sites or Test User functionality, so real reports are used for testing). Once the test is confirmed, the partner can call the report again so they can post into the production ERP.

Headers

Payload

None.

Response

Status Codes

Headers

Payload

Financial Documents

Example

Request

GET https://us.api.concursolutions.com/financialintegration/fi/v4/companies/transactiontypes/expense/transactions?limit=3
Authorization: Bearer {token}

Response

200 OK
Content-Type: application/json
Date: {date-requested}
Content-Length: 491
{
  "links" : [ {
    "rel" : "first",
    "href" : "https://fiserviceurlhere/fi/v4/companies/transactiontypes/expense/transactions?limit=3&page=0&size=3",
    "hreflang" : null,
    "media" : null,
    "title" : null,
    "type" : null,
    "deprecation" : null
  }, {
    "rel" : "self",
    "href" : "https://fiserviceurlhere/fi/v4/companies/transactiontypes/expense/transactions?limit=3&page=0&size=3",
    "hreflang" : null,
    "media" : null,
    "title" : null,
    "type" : null,
    "deprecation" : null
  }, {
    "rel" : "next",
    "href" : "https://fiserviceurlhere/fi/v4/companies/transactiontypes/expense/transactions?limit=3&page=1&size=3",
    "hreflang" : null,
    "media" : null,
    "title" : null,
    "type" : null,
    "deprecation" : null
  }, {
    "rel" : "last",
    "href" : "https://fiserviceurlhere/fi/v4/companies/transactiontypes/expense/transactions?limit=3&page=2&size=3",
    "hreflang" : null,
    "media" : null,
    "title" : null,
    "type" : null,
    "deprecation" : null
  } ],
  "content" : [ {
    "id" : "e7f810cabc8348cdb051dd9431c8cfbb",
    "docType" : "expense",
    "companyId" : "COMPANY_ID_HERE",
    "entityId" : "ENTITY_ID_HERE",
    "companyUuid" : "COMPANY_UUID_HERE",
    "erpSystemId" : "",
    "document" : "{THE_FINANCIAL_DOCUMENT}",
    "docStatus" : "READY",
    "links" : [ ]
  }, {
    "id" : "e1500222f16748718fdd2d493ee4c9dd",
    "docType" : "expense",
    "companyId" : "COMPANY_ID_HERE",
    "entityId" : "ENTITY_ID_HERE",
    "companyUuid" : "COMPANY_UUID_HERE",
    "erpSystemId" : null,
    "document" : "{THE_FINANCIAL_DOCUMENT}",
    "docStatus" : "READY",
    "links" : [ ]
  }, {
    "id" : "e2135678f16748718fdd2d493ee4c9dd",
    "docType" : "expense",
    "companyId" : "COMPANY_ID_HERE",
    "entityId" : "ENTITY_ID_HERE",
    "companyUuid" : "COMPANY_UUID_HERE",
    "erpSystemId" : null,
    "document" : "{THE_FINANCIAL_DOCUMENT}",
    "docStatus" : "READY",
    "links" : [ ]
  }
   ],
  "page" : {
    "size" : 3,
    "totalElements" : 8,
    "totalPages" : 3,
    "number" : 0
  }
}

Post Financial Transaction Acknowledgements

Allows an external system to acknowledge that it has successfully retrieved one or more financial transactions from SAP Concur and will begin processing those transactions. The transactions in the POST request are then taken out of the ready queue.

An app should execute the POST request immediately after the GET request. Eliminating any time between the requests will avoid a variance between the ERP and SAP Concur. For example, if there is a time lag, the customer administrator could use the SAP Concur Processor tool to recall or send a report (or invoice) back to the report owner where he or she can change it or even delete it. This would create a discrepancy between SAP Concur and the ERP.

Scopes

FISVC - Refer to Scope Usage for full details.

Request

URI

Template
https://{datacenterURI}/financialintegration/fi/v4/companies/transactiontypes/{docType}/transactions/acknowledgements
Parameters
Name Type Format Description
docType string path Required The financial document type. Only one type of transaction can be acknowledged at a time. Supported values: expense, invoice, cashadvance, payroll, obligation.

Headers

Payload

AcknowledgeRequest

Response

Status Codes

Headers

Payload

AcknowledgeResponse

Example

Request

POST https://us.api.concursolutions.com/financialintegration/fi/v4/companies/transactiontypes/expense/transactions/acknowledgements
Authorization: Bearer {token}
Content-Type: application/json
{
  "ids": [ "5ab9224e02e840148e7cd7d9e8e72968", "2ac9224e02e840148e7cd7d9e8e12345" ]
}

Response

This response shows both success and failure service code examples.

200 OK
Content-Type: application/json
Date: {date-requested}
Content-Length: 372
[
  {
    "code": 0,
    "docId": "5ab9224e02e840148e7cd7d9e8e72968",
    "systemId": null,
    "acknowledgeResult": "SUCCESS",
    "errorMessage": ""
  },
  {
    "code": 101,
    "docId": "2ac9224e02e840148e7cd7d9e8e12345",
    "systemId": null,
    "acknowledgeResult": "FAILURE",
    "errorMessage": "This document was previously acknowledged by SystemId: null."
  }
]

Post Financial Transactions Confirmations

Allows financial posting results to be sent to SAP Concur.

Scopes

FISVC - Refer to Scope Usage for full details.

Request

URI

Template
https://{datacenterURI}/financialintegration/fi/v4/companies/transactiontypes/{docType}/transactions/postingconfirmations
Parameters
Name Type Format Description
docType string path Required The financial document type to return. Only one type of transaction can be retrieved at a time. Supported values: expense, invoice, cashadvance, payroll, obligation
confirmationRequest - body Required The JSON request to be posted.

Headers

Payload

Confirmation Request

Response

Status Codes

Headers

Payload

Posting Confirmation Response

Example

Request

POST https://us.api.concursolutions.com/financialintegration/fi/v4/companies/transactiontypes/expense/transactions/postingconfirmations
Authorization: Bearer {token}
Content-Type: application/json
{
  "systemId":"",
  "postingConfirmations":
  [
    {
      "docId":"0c06ab044834454d91f83cbd7b6431d2",
      "overallPostingStatusCode":"error",
      "postingDocs":[],
      "systemMessages":
      [
        {
          "concurTransactionLineItemId":"",
          "messageId":"010-CTE-POSTING",
          "messageLanguage":"EN",
          "messageLongText":"",
          "messageShortText":"Expense Report {ReportKey} of system CONCUR could not be posted."
        },
        {
          "concurTransactionLineItemId":"",
          "messageId":"003-CC",
          "messageLanguage":"EN",
          "messageLongText":"",
          "messageShortText":"Profit centre /company code assignment is not correct. Check the entry."
        }
      ]
    },
    {
      "docId":"3331dbeb8e2240ffad7ab5b69492722a",
      "overallPostingStatusCode":"success",
      "postingDocs":
      [
        {
          "companyId":"0100",
          "documentNumber":"0123456",
          "fiscalYear":"2018",
          "paymentRelevantLineItems":[],
          "postingDate":"2018-03-02"
        },
        {
          "companyId":"0800",
          "documentNumber":"0123478",
          "fiscalYear":"2018",
          "paymentRelevantLineItems":[],
          "postingDate":"2018-03-02"
        }
      ],
      "systemMessages":[]
    }
  ]
}

Response

This response shows both success and failure service code examples.

200 OK
Content-Type: application/json
Date: {date-requested}
Content-Length: 405
[
  {
    "code": 0,
    "docId": "0c06ab044834454d91f83cbd7b6431d2",
    "systemId": null,
    "postingConfirmationResult": "SUCCESS",
    "errorMessage": "",
    "detailMessage": ""
  },
  {
    "code": 116,
    "docId": "3331dbeb8e2240ffad7ab5b69492722a",
    "systemId": "",
    "postingConfirmationResult": "FAILURE",
    "errorMessage": "This document does not exist.",
    "detailMessage": ""
  }
]

Post Financial Payment Confirmations

Allows financial payment results to be sent to SAP Concur.

Scopes

FISVC - Refer to Scope Usage for full details.

Request

URI

Template
https://{datacenterURI}/financialintegration/fi/v4/companies/transactiontypes/{docType}/transactions/paymentconfirmations
Parameters
Name Type Format Description
docType string path Required The financial document type to return. Only one type of transaction can be retrieved at a time. Supported values: expense, invoice, cashadvance, payroll, obligation
confirmationRequest body Required The JSON request to be posted.

Headers

Payload

Payment Confirmation Request

Response

Status Codes

Headers

Payload

Payment Confirmation Response

Example

Request

POST https://us.api.concursolutions.com/financialintegration/fi/v4/companies/transactiontypes/expense/transactions/paymentconfirmations
Authorization: Bearer {token}
Content-Type: application/json
{
  "systemId":"",
  "processingConfirmation":
  [
    {
      "docId":"0c06ab044834454d91f83cbd7b6431d2",
      "processingStatusCode":"CP",
      "clearingDetails":[
        {
          "clearingDate":"2019-02-06T12:00:00.27Z","clearingAmount":220.00,
          "clearingCurrency":"USD","receiver":{"receiverId":"22344",
          "receiverName":"Charles","receiverType":"EMPLOYEE"},
          "clearingReference":{"companyCode":"US01","financialDocumentId":"667799",
          "fiscalYear":"2019","paymentRef":"US01/667799/2019/2","paymentMethod":"E"}
        }
      ]
    },
    {
      "docId":"454d91f83cbd7b6431d20c06ab044834",
      "processingStatusCode":"PP",
      "clearingDetails":[
        {
          "clearingDate":"2019-02-06T12:00:00.27Z","clearingAmount":40.00,
          "clearingCurrency":"USD","receiver":{"receiverId":"57",
          "receiverName":"John","receiverType":"EMPLOYEE"},
          "clearingReference":{"companyCode":"US01","financialDocumentId":"996675",
          "fiscalYear":"2019","paymentRef":"US01/996675/2019/2","paymentMethod":"E"}
        }
      ]
    },
    {
      "docId":"1d20c06ab0445d7b64348344d91f83cb",
      "processingStatusCode":"PP",
      "clearingDetails":[
        {
          "clearingDate":"2019-02-06T12:00:00.27Z","clearingAmount":23.00,
          "clearingCurrency":"USD","receiver":{"receiverId":"57",
          "receiverName":"Alice","receiverType":"EMPLOYEE"},
          "clearingReference":{"companyCode":"US01","financialDocumentId":"95432",
          "fiscalYear":"2019","paymentRef":"US01/95432/2019/2","paymentMethod":"E"}
        }
      ]
    },
    {
      "docId":"d2454d91fcb44834830c06ab0d7b6431",
      "processingStatusCode":"RE",
      "additionalMessage":"This report was sent to wrong system",
      "clearingDetails":[
        {
          "clearingDate":"2019-02-06T12:00:00.27Z","clearingAmount":10.00,
          "clearingCurrency":"USD","receiver":{"receiverId":"57",
          "receiverName":"Peter","receiverType":"EMPLOYEE"},
          "clearingReference":{"companyCode":"US01","financialDocumentId":"5498",
          "fiscalYear":"2019","paymentRef":"US01/5498/2019/2","paymentMethod":"E"}
        }
      ]
    },
    {
      "docId":"b6431d2454dcbd791f44834830c06ab0",
      "processingStatusCode":"OB",
      "additionalMessage":"Not required anymore",
      "clearingDetails":[
        {
          "clearingDate":"2019-02-06T12:00:00.27Z","clearingAmount":54.00,
          "clearingCurrency":"USD","receiver":{"receiverId":"57",
          "receiverName":"Kevin","receiverType":"EMPLOYEE"},
          "clearingReference":{"companyCode":"US01","financialDocumentId":"32478",
          "fiscalYear":"2019","paymentRef":"US01/32478/2019/2","paymentMethod":"E"}
        }
      ]
    }
  ]
}

Response

This response shows both success and failure service code examples.

200 OK
Content-Type: application/json
Date: {date-requested}
Content-Length: 405
[
  {
  "code" : 0,
  "docId" : "0c06ab044834454d91f83cbd7b6431d2",
  "systemId" : "",
  "paymentConfirmationResult" : "SUCCESS",
  "errorMessage" : null,
  "paymentRef" : "US01/667799/2019/2",
  "detailMessage" : ""
  },
  {
  "code" : 116,
  "docId" : "454d91f83cbd7b6431d20c06ab044834",
  "systemId" : "",
  "paymentConfirmationResult" : "FAILURE",
  "errorMessage" : "This document does not exist.",
  "paymentRef" : "US01/996675/2019/2",
  "detailMessage" : ""
  },
  {
  "code" : 298,
  "docId" : "1d20c06ab0445d7b64348344d91f83cb",
  "systemId" : "",
  "paymentConfirmationResult" : "NOOP",
  "errorMessage" : "Payment confirmation already exist US01/95432/2019/2.",
  "paymentRef" : "US01/95432/2019/2",
  "detailMessage" : ""
  }
  {
  "code" : 0,
  "docId" : "d2454d91fcb44834830c06ab0d7b6431",
  "systemId" : "",
  "paymentConfirmationResult" : "SUCCESS",
  "errorMessage" : null,
  "paymentRef" : "US01/5498/2019/2",
  "detailMessage" : ""
  },
  {
  "code" : 0,
  "docId" : "b6431d2454dcbd791f44834830c06ab0",
  "systemId" : "",
  "paymentConfirmationResult" : "SUCCESS",
  "errorMessage" : null,
  "paymentRef" : "US01/32478/2019/2",
  "detailMessage" : ""
  }
]

Service Codes

The Financial Integration Service will return service codes based on the success and failure of individual records for acknowledging and posting confirmation of documents.

Code Description Category
0 Successfully processed Any
99 System ID in request does not match system ID in FI database. Any
101 This document was previously acknowledged. Acknowledge
102 This document has been recalled. Acknowledge
103 This document is not ready. Acknowledge
104 This document does not exist in the FI database. Acknowledge
105 This document is not of type (expense, invoice, cashadvance). Acknowledge
111 This document has not been acknowledged. Posting
112 This document has been recalled. Posting
113 Confirmation has been posted for this document. Posting
114 Document is not in a known state. Posting
115 This document is not of type (expense, invoice, cashadvance). Posting
116 This document does not exist in the FI database. Posting
198 Invalid request - this same request will not work if tried again. Posting
199 Unknown error, please try again later. Any

Schema

Financial Documents

Name Type Format Description
content Array FIDocument The result collection.
page string PageMetadata Pagination details.
links Array Link Pagination links.

FIDocument

Name Type Format Description
id string - The unique identifier for the document.
docType string - Transaction type. Supported values: expense, invoice, cashadvance, payroll, obligation.
companyId string - Unique identifier for the company in SAP Concur. Maximum 32 characters.
entityId string - Unique identifier for the entity in SAP Concur. Maximum 32 characters.
companyUuid string UUID UUID for the company in SAP Concur. Maximum 36 characters.
erpSystemId string - The external System ID that processed the document. Maximum 50 characters.
document Array - The JSON financial document. Review the FI sample documents below.
docStatus string - The financial document status. Supported values: READY, ACKNOWLEDGED, POSTING_CONFIRMED_SUCCESS, POSTING_CONFIRMED_FAILURE.

PageMetadata

Name Type Format Description
size int32 - Total number of pages returned.
totalElements int32 - Total count of records returned.
totalPages int32 - Total number of pages returned.
number int32 - Page location for which the result is returned, for example: first page starts with 0, second page starts with 1.
Name Type Format Description
rel string - Relation of link, for example: first, self, next, last.
href string - Complete URL for the paginated link.
hreflang string - Link language, if any.
media string - Media type, if any.
title string - Link title, if any.
type string - Link type, if any.
deprecation string - Deprecated indication, if any.

AcknowledgeRequest

Name Type Format Description
ids Array string The unique identifiers list for the financial documents.
systemId string - The external system ID that acknowledged the documents.

AcknowledgeResponse

Name Type Format Description
AcknowledgeResponse array AcknowledgeResponseItem The JSON response.

AcknowledgeResponseItem

Name Type Format Description
acknowledgeResult string - Acknowledge processing result. Supported values are: SUCCESS or FAILURE.
code Int32 Service Codes The Financial Integration Service Code. This is a particular code based on the success and failure of individual records for Acknowledging documents.
docId string - The financial document unique identifier. Maximum 32 characters.
errorMessage string - The error message, if any.
systemId string - The external system ID that acknowledged the documents. Maximum 50 characters.

Confirmation Request

Name Type Format Description
systemId string - Required The external system ID that acknowledged the documents, it can be an empty string. Maximum 50 characters.
postingConfirmations Array Posting Confirmation request item Posting confirmations JSON request.

Posting Confirmation Request Item

Name Type Format Description
docId string - Required The financial document ID to confirm. Maximum 32 characters.
overallPostingStatusCode string - Required Posting status. VALUES: error or success.
postingDocs array Posting Documents Details Posting documents details, if any.
systemMessages array System Messages Required Messages to post to SAP Concur, if any.

Posting Documents Details

Name Type Format Description
companyId string - Required External system organizational unit ID. Maximum 32 characters.
documentNumber string - External system document identifier. Maximum 80 characters.
fiscalYear int32 - External system fiscal year.
paymentRelevantLineItems array - Payment relevant line items. This array is usually empty.
postingDate string YYYY-MM-DD External system posting date.

System Messages

Name Type Format Description
concurTransactionLineItemId string - Report relevant line item id.
messageId string - External System message identifier.
messageLanguage string - Message Language code, example EN, FR.
messageLongText array - Message text, will be posted on the audit trail in SAP Concur. Maximum 1300 characters.
messageShortText string - Message text, will be posted on the audit trail in SAP Concur. Maximum 1300 characters.

Posting Confirmation Response

Name Type Format Description
PostingConfirmationResponse array Posting Confirmation Response Item The JSON response body.

PostingConfirmationResponseItem

Name Type Format Description
postingConfirmationResult string - Posting confirmation result. Supported values: SUCCESS, SYSTEM_ERROR_OCCURRED, NOT_YET_ACKNOWLEDGED, DOCUMENT_NOT_FOUND, FAILURE, WAS_RECALLED
detailMessage string - Posting confirmation message.
code Int32 - The Financial Service return code.
docId string - The document ID. Maximum 32 characters.
errorMessage string - The error message, if any.
systemId string - The external system ID that acknowledged the document. Maximum 50 characters.

Payment Confirmation Request

Name Type Format Description
systemId string - Required The external system ID that acknowledged the documents, it can be an empty string. Maximum 50 characters.
processingConfirmation Array Payment Confirmation Request Item Payment confirmations JSON request.

Payment Confirmation Request Item

Name Type Format Description
docId string - The financial document ID to confirm. Maximum 32 characters.
processingStatusCode string - Payment status. Supported values: CP, PP, RE, OB (Completely Paid, Partially paid, Reversal, Obsolete). Maximum 3 characters.
additionalMessage string - Reversal message or obsolete message, if any.
clearingDetails array Payment Documents Details Payment documents details, if any.

Payment Documents Details

Name Type Format Description
clearingDate string - Date the payment cleared.
clearingAmount double - Amount cleared.
clearingCurrency string - Currency value.
receiver array Receiver Details Receiver details.
clearingReference array Clearing Reference Details Clearing reference details.

Receiver Details

Name Type Format Description
receiverId string - Receiver ID.
receiverName double - Name of receiver.
receiverType string - Type of receiver.

Clearing Reference Details

Name Type Format Description
companyCode string - Company code.
financialDocumentId string - Document ID in ERP.
fiscalYear string - Fiscal year.
paymentRef string - Payment reference ID.
paymentMethod string - Payment method Where E = Electronic Fund Transfer or C = Check.

Payment Confirmation Response

Name Type Format Description
PaymentConfirmationResponse array Payment Confirmation Response Item The JSON response body

PaymentConfirmationResponseItem

Name Type Format Description
paymentConfirmationResult string - Payment confirmation result. Supported values: SUCCESS, SYSTEM_ERROR_OCCURRED, NOT_POSTING_CONFIRMED, DOCUMENT_NOT_FOUND, FAILURE, NOOP
paymentRef string - Any message corresponding to payment reference being processed.
detailMessage string - Payment confirmation message.
code Int32 - The financial service return code.
docId string - The document ID. Maximum 32 characters.
errorMessage string - The error message, if any.
systemId string - The external system ID that acknowledged the document. Maximum 50 characters.

Example Financial Documents

Expense

{
   "employee": {
      "employeeFirstName": "FirstName",
      "employeeLastName": "LastName",
      "employeeId": "12345AB",
      "employeeMI": null,
      "employeeOrgUnit4Value": null,
      "employeeOrgUnit5Value": null,
      "employeeOrgUnit6Value": null,
      "employeeCustom1Code": null,
      "employeeCustom2Code": null,
      "employeeCustom3Code": null,
      "employeeCustom4Code": "001",
      "employeeCustom5Code": "USPUG",
      "employeeCustom6Code": "1234",
      "employeeCustom7Code": null,
      "employeeCustom8Code": null,
      "employeeCustom9Code": null,
      "employeeCustom10Code": null,
      "employeeCustom11Code": null,
      "employeeCustom12Code": null,
      "employeeCustom13Code": null,
      "employeeCustom14Code": null,
      "employeeCustom15Code": null,
      "employeeCustom16Code": "N",
      "employeeCustom17Code": null,
      "employeeCustom18Code": null,
      "employeeCustom19Code": null,
      "employeeCustom20Code": null,
      "employeeCustom21Code": "US Group",
      "employeeCustom1Value": null,
      "employeeCustom2Value": null,
      "employeeCustom3Value": null,
      "employeeCustom4Value": "US Inc.",
      "employeeCustom5Value": "US Publishing",
      "employeeCustom6Value": "Operations",
      "employeeCustom7Value": null,
      "employeeCustom8Value": null,
      "employeeCustom9Value": null,
      "employeeCustom10Value": null,
      "employeeCustom11Value": null,
      "employeeCustom12Value": null,
      "employeeCustom13Value": null,
      "employeeCustom14Value": null,
      "employeeCustom15Value": null,
      "employeeCustom16Value": null,
      "employeeCustom17Value": null,
      "employeeCustom18Value": null,
      "employeeCustom19Value": null,
      "employeeCustom20Value": null,
      "employeeCustom21Value": "US Group",
      "employeeOrgUnit1Code": null,
      "employeeOrgUnit2Code": null,
      "employeeOrgUnit3Code": null,
      "employeeOrgUnit4Code": null,
      "employeeOrgUnit5Code": null,
      "employeeOrgUnit6Code": null,
      "employeeOrgUnit1Value": null,
      "employeeOrgUnit2Value": null,
      "employeeOrgUnit3Value": null
   },
   "report": {
      "reportKey": 345,
      "ledgerCode": "DEFAULT",
      "reportId": "D0719B539ED64FE612AB",
      "totalApprovedAmount": 200,
      "reportName": "Trip to Minneapolis",
      "isTest": "N",
      "reportStartDate": null,
      "reportEndDate": null,
      "employeeCurrencyAlphaCode": "USD",
      "payrollPayIndicator": "N",
      "payrollPaymentClearingAccountCode": null,
      "cashAdvanceReturnsAmount": 0E-8,
      "revisionNumber": "1",
      "versionId": "4",
      "homeCountryCode": "US",
      "reportCustom20Code": null,
      "reportCustom1Value": null,
      "reportCustom2Value": null,
      "reportCustom3Value": null,
      "reportCustom4Value": null,
      "reportCustom5Value": null,
      "reportCustom6Value": null,
      "reportCustom7Value": null,
      "reportCustom8Value": null,
      "reportCustom9Value": null,
      "reportCustom10Value": null,
      "reportCustom11Value": null,
      "reportCustom12Value": null,
      "reportCustom13Value": null,
      "reportCustom14Value": null,
      "reportCustom15Value": "US Group",
      "reportCustom16Value": null,
      "reportCustom17Value": null,
      "reportCustom18Value": null,
      "reportCustom19Value": null,
      "reportCustom20Value": null,
      "reportOrgUnit1Code": null,
      "reportOrgUnit2Code": null,
      "reportOrgUnit3Code": null,
      "reportOrgUnit4Code": null,
      "reportOrgUnit5Code": null,
      "reportOrgUnit6Code": null,
      "reportOrgUnit1Value": null,
      "reportOrgUnit2Value": null,
      "reportCustom5Code": null,
      "reportCustom6Code": null,
      "reportCustom7Code": null,
      "reportCustom8Code": null,
      "reportCustom9Code": null,
      "reportCustom10Code": null,
      "reportCustom11Code": null,
      "reportCustom12Code": null,
      "reportCustom13Code": null,
      "reportCustom14Code": null,
      "reportCustom15Code": "US Group",
      "reportCustom16Code": "12345AB",
      "reportCustom17Code": null,
      "reportCustom18Code": null,
      "reportCustom19Code": null,
      "reportSubmitDate": "2018-03-02T18:12:03.050Z",
      "reportUserDefinedDate": "2018-03-02T00:00:00.000Z",
      "reportPaymentProcessingDate": "2018-03-02T18:34:30.260Z",
      "reportCreationDate": "2018-03-02T18:08:37.887Z",
      "reportCustom1Code": "12345AB",
      "reportCustom2Code": null,
      "reportCustom3Code": null,
      "reportCustom4Code": null,
      "reportOrgUnit3Value": null,
      "reportOrgUnit4Value": null,
      "reportOrgUnit5Value": null,
      "reportOrgUnit6Value": null
   },
   "expenseEntry": [
      {
         "cardProgramTypeCode": null,
         "entryCustom20Code": null,
         "entryCustom21Code": null,
         "entryCustom22Code": null,
         "entryCustom23Code": null,
         "entryCustom24Code": null,
         "entryCustom25Code": null,
         "entryCustom26Code": null,
         "entryCustom27Code": null,
         "entryCustom28Code": null,
         "entryCustom29Code": null,
         "entryCustom30Code": null,
         "entryCustom31Code": null,
         "entryCustom32Code": null,
         "entryCustom33Code": null,
         "entryCustom34Code": null,
         "entryCustom35Code": "US",
         "entryCustom36Code": null,
         "entryCustom37Code": null,
         "entryCustom38Code": null,
         "entryCustom39Code": "0.00000000",
         "entryCustom40Code": "200.00000000",
         "reportEntryTransactionAmount": 200,
         "entryLocationCityName": "Minneapolis",
         "entryCountrySubCode": "US-MN",
         "entryIsBillable": "N",
         "entryOrgUnit1Code": null,
         "entryOrgUnit2Code": null,
         "entryOrgUnit3Code": null,
         "entryOrgUnit4Code": null,
         "entryOrgUnit5Code": null,
         "entryOrgUnit6Code": null,
         "offsetPayType": "N",
         "entryCountryCode": "US",
         "entryUuid": null,
         "entrySupplierTaxID": null,
         "entryCustom1Code": null,
         "entryCustom2Code": null,
         "entryCustom3Code": null,
         "entryCustom4Code": null,
         "entryCustom5Code": null,
         "entryCustom6Code": null,
         "entryCustom7Code": null,
         "entryCustom8Code": null,
         "entryCustom9Code": null,
         "entryCustom10Code": null,
         "entryCustom11Code": null,
         "entryCustom12Code": null,
         "entryCustom13Code": null,
         "entryCustom14Code": null,
         "entryCustom15Code": null,
         "entryCustom16Code": null,
         "entryCustom17Code": null,
         "entryCustom18Code": null,
         "entryCustom19Code": null,
         "cardAccountID": null,
         "cardTransactionID": null,
         "cardTransactionAmount": null,
         "cardTransactionCurrency": null,
         "cardTransactionPostedAmount": null,
         "cardTransactionPostedCurrency": null,
         "clearingAccountCode": null,
         "entryApprovedAmount": 200,
         "expensePayIndicator": "N",
         "entryId": "A92F3AD820F4E546800515258C3E0893",
         "entryDescription": "",
         "entryVendorCode": "Astron Hotels",
         "entryCustom1Value": null,
         "entryCustom2Value": null,
         "entryCustom3Value": null,
         "entryCustom4Value": null,
         "entryCustom5Value": null,
         "entryCustom6Value": null,
         "entryCustom7Value": null,
         "entryCustom8Value": null,
         "entryCustom9Value": null,
         "entryCustom10Value": null,
         "entryCustom11Value": null,
         "entryCustom12Value": null,
         "entryCustom13Value": null,
         "entryCustom14Value": null,
         "entryCustom15Value": null,
         "entryCustom16Value": null,
         "entryCustom17Value": null,
         "entryCustom18Value": null,
         "entryCustom19Value": null,
         "entryCustom20Value": null,
         "entryCustom21Value": null,
         "entryCustom22Value": null,
         "entryCustom23Value": null,
         "entryCustom24Value": null,
         "entryCustom25Value": null,
         "entryCustom26Value": null,
         "entryCustom27Value": null,
         "entryCustom28Value": null,
         "entryCustom29Value": null,
         "entryCustom30Value": null,
         "entryCustom31Value": null,
         "entryCustom32Value": null,
         "entryCustom33Value": null,
         "entryCustom34Value": null,
         "entryCustom35Value": null,
         "entryCustom36Value": null,
         "entryCustom37Value": null,
         "entryCustom38Value": null,
         "entryCustom39Value": null,
         "entryCustom40Value": null,
         "entryOrgUnit1Value": null,
         "entryOrgUnit2Value": null,
         "entryOrgUnit3Value": null,
         "entryOrgUnit4Value": null,
         "entryOrgUnit5Value": null,
         "entryOrgUnit6Value": null,
         "entryLocationName": "Minneapolis",
         "entryReceiptId": "E921EECCBCBA393EAC5A9212DCE57D9B",
         "entryElectronicReceiptId": null,
         "allocation": [
            {
               "allocationId": "76A1774FEC7D0C4981FBB332AB5671A3",
               "allocationCustom1Code": "",
               "allocationCustom2Code": "",
               "allocationCustom3Code": "",
               "allocationCustom4Code": null,
               "allocationCustom5Code": null,
               "allocationCustom6Code": null,
               "allocationCustom7Code": null,
               "allocationCustom8Code": null,
               "allocationCustom9Code": null,
               "allocationCustom10Code": null,
               "allocationCustom11Code": null,
               "allocationCustom12Code": null,
               "allocationCustom13Code": null,
               "allocationCustom14Code": null,
               "allocationCustom15Code": null,
               "allocationCustom16Code": null,
               "allocationCustom17Code": null,
               "allocationCustom18Code": null,
               "allocationCustom19Code": null,
               "allocationCustom20Code": null,
               "allocationCustom1Value": null,
               "allocationCustom2Value": null,
               "allocationCustom3Value": null,
               "allocationCustom4Value": null,
               "allocationCustom5Value": null,
               "allocationCustom6Value": null,
               "allocationCustom7Value": null,
               "allocationCustom8Value": null,
               "allocationCustom9Value": null,
               "allocationCustom10Value": null,
               "allocationCustom11Value": null,
               "allocationCustom12Value": null,
               "allocationCustom13Value": null,
               "allocationCustom14Value": null,
               "allocationCustom15Value": null,
               "allocationCustom16Value": null,
               "allocationCustom17Value": null,
               "allocationCustom18Value": null,
               "allocationCustom19Value": null,
               "allocationCustom20Value": null,
               "allocationPercentage": 100,
               "journal": [
                  {
                     "amountGrossCard": null,
                     "journalAccountCode": "125ABC",
                     "journalPayee": "EMPL",
                     "journalPayer": "COMP",
                     "cardTransactionReferenceNumber": null,
                     "amountNetOfReclaim": 150,
                     "amountNetOfTax": 150,
                     "amountGross": 150,
                     "taxGuid": [],
                     "accountingTransactionType": null
                  },
                  {
                     "amountGrossCard": null,
                     "journalAccountCode": "12345",
                     "journalPayee": "EMPL",
                     "journalPayer": "COMP",
                     "cardTransactionReferenceNumber": null,
                     "amountNetOfReclaim": 50,
                     "amountNetOfTax": 50,
                     "amountGross": 50,
                     "taxGuid": [],
                     "accountingTransactionType": null
                  }
               ],
               "tax": []
            }
         ],
         "entryReceiptType": "N",
         "entryExchangeRateDirection": "M",
         "entryIsPersonal": "N",
         "entryVendorDescription": "Astron Hotels",
         "legacyEntryId": 294,
         "liabilityAccountCode": null,
         "expenseTypeName": "Hotel",
         "entryDate": "2018-02-17T00:00:00.000Z",
         "entryCurrAlphaCode": "USD",
         "entryExchangeRate": 1,
         "expenseTypeCode": "LODNG",
         "cardStatementPeriodStartDate": null,
         "cardStatementPeriodEndDate": null,
         "reportEntryPatKey": "CASH"
      }
   ],
   "cashAdvanceApplication": [
      {
         "cashAdvanceClearingAccountCode": "12345",
         "cashAdvanceId": "6A107A548D1B4B49BBF370DF02EC890D",
         "cashAdvanceApplicationAmount": -50,
         "cashAdvanceTransactionType": 2
      }
   ]
}

Invoice

{
   "requestHeader":{
      "ledgerCode":"DEFAULT",
      "clearingAccountCode":null,
      "invoiceDate":"08/08/2018",
      "reqKey":35,
      "postingDate":null,
      "poNumber":null,
      "isTest":"N",
      "deliverySlipNumber":null,
      "discountPercentage":null,
      "paymentDueDate":"09/07/2018",
      "requestId":"9B1D30723CBF4F86A574",
      "requestOrgUnit4Code":null,
      "requestOrgUnit5Code":null,
      "requestOrgUnit6Code":null,
      "currencyAlphaCode":"USD",
      "ledgerName":"DEFAULT",
      "vendorInvoiceNumber":"25688",
      "multiplePurchaseOrder":"N",
      "invoicePayIndicator":"N",
      "payMethodType":"CLIENT",
      "submitDate":"2018-09-05T03:37:42.923Z",
      "requestTotal":50.00000000,
      "revisionNumber":"1",
      "processCompleteDate":null,
      "invoiceReceivedDate":null,
      "requestOrgUnit1Value":null,
      "requestOrgUnit2Value":null,
      "requestOrgUnit3Value":null,
      "requestOrgUnit4Value":null,
      "requestOrgUnit5Value":null,
      "requestOrgUnit6Value":null,
      "versionId":"4",
      "requestOrgUnit1Code":null,
      "requestOrgUnit2Code":null,
      "requestOrgUnit3Code":null,
      "requestCustom21Code":null,
      "requestCustom22Code":null,
      "requestCustom1Value":null,
      "requestCustom2Value":null,
      "requestCustom3Value":null,
      "requestCustom4Value":null,
      "requestCustom5Value":null,
      "requestCustom6Value":null,
      "requestCustom7Value":null,
      "requestCustom8Value":null,
      "requestCustom9Value":null,
      "requestCustom10Value":"Default-Change to Client",
      "requestCustom11Value":null,
      "requestCustom12Value":null,
      "requestCustom13Value":null,
      "requestCustom14Value":null,
      "requestCustom15Value":null,
      "requestCustom16Value":null,
      "requestCustom17Value":null,
      "requestCustom18Value":null,
      "requestCustom19Value":null,
      "requestCustom20Value":null,
      "requestCustom21Value":null,
      "requestCustom22Value":null,
      "requestCustom23Value":null,
      "requestCustom24Value":null,
      "amountNetInvoice":50.00000000,
      "amountShippingTotal":0E-8,
      "requestTitle":"FIS Test",
      "discountTermsDays":null,
      "requestCustom1Code":null,
      "requestCustom2Code":null,
      "requestCustom3Code":null,
      "requestCustom4Code":null,
      "requestCustom5Code":null,
      "requestCustom6Code":null,
      "requestCustom7Code":null,
      "requestCustom8Code":null,
      "requestCustom9Code":null,
      "requestCustom10Code":"Default",
      "requestCustom11Code":null,
      "requestCustom12Code":null,
      "requestCustom13Code":null,
      "requestCustom14Code":null,
      "requestCustom15Code":null,
      "requestCustom16Code":null,
      "requestCustom17Code":null,
      "requestCustom18Code":null,
      "requestCustom19Code":null,
      "requestCustom20Code":null,
      "requestCustom24Code":null,
      "netPaymentTermDays":"30",
      "requestCreationDate":"2018-09-05T03:37:00.143Z",
      "requestCustom23Code":null,
      "requestDescription":null
   },
   "ownerEmployee":{
      "employeeCustom20Value":null,
      "employeeCustom21Value":"System",
      "employeeCustom10Code":"Default",
      "employeeOrgUnit1Code":null,
      "employeeOrgUnit2Code":null,
      "employeeOrgUnit3Code":null,
      "employeeOrgUnit4Code":null,
      "employeeOrgUnit5Code":null,
      "employeeOrgUnit6Code":null,
      "employeeOrgUnit1Value":null,
      "employeeOrgUnit2Value":null,
      "employeeOrgUnit3Value":null,
      "employeeOrgUnit4Value":null,
      "employeeOrgUnit5Value":null,
      "employeeOrgUnit6Value":null,
      "employeeCustom1Code":"ext-record-4",
      "employeeCustom2Code":null,
      "employeeCustom3Code":null,
      "employeeCustom4Code":null,
      "employeeCustom5Code":null,
      "employeeCustom6Code":null,
      "employeeCustom7Code":null,
      "employeeCustom8Code":null,
      "employeeCustom9Code":"28",
      "employeeCustom11Code":null,
      "employeeCustom13Code":null,
      "employeeCustom14Code":null,
      "employeeCustom15Code":null,
      "employeeCustom16Code":"N",
      "employeeCustom17Code":null,
      "employeeCustom18Code":null,
      "employeeCustom19Code":null,
      "employeeCustom20Code":null,
      "employeeCustom21Code":"SYS",
      "employeeCustom1Value":null,
      "employeeCustom2Value":null,
      "employeeCustom3Value":null,
      "employeeCustom4Value":null,
      "employeeCustom5Value":null,
      "employeeCustom6Value":null,
      "employeeCustom7Value":null,
      "employeeCustom8Value":null,
      "employeeCustom9Value":"522 Product",
      "employeeCustom10Value":"Default-Change to Client",
      "employeeCustom11Value":null,
      "employeeCustom12Value":null,
      "employeeCustom13Value":null,
      "employeeCustom14Value":null,
      "employeeCustom15Value":null,
      "employeeCustom16Value":null,
      "employeeCustom17Value":null,
      "employeeCustom18Value":null,
      "employeeCustom19Value":null,
      "employeeId":"12345AB",
      "employeeMI":"C",
      "employeeFirstName":"FirstName",
      "employeeLastName":"LastName",
      "employeeCustom12Code":null
   },
   "vendor":{
      "vendorName":"Test Vendor",
      "vendorCode":"94F538F2C3224C6E871CFED9F0F8333A",
      "vendorShipFromAddressCode":null,
      "vendorRemitToAddressCode":"333",
      "vendorContactFirstName":null,
      "vendorContactLastName":null
   },
   "lineItem":[
      {
         "allocation":[
            {
               "journal":{
                  "accountCode":"MATER",
                  "amountShipping":0,
                  "amountNet":50.00,
                  "amountGross":50.00,
                  "tax":null
               },
               "allocationAccountCode":"MATER",
               "allocationCustom6Code":null,
               "allocationCustom7Code":null,
               "allocationCustom8Code":null,
               "allocationCustom9Code":null,
               "allocationCustom10Code":null,
               "allocationCustom11Code":null,
               "allocationCustom12Code":null,
               "allocationCustom13Code":null,
               "allocationCustom14Code":null,
               "allocationCustom15Code":null,
               "allocationCustom16Code":null,
               "allocationCustom17Code":null,
               "allocationCustom18Code":null,
               "allocationCustom19Code":null,
               "allocationCustom20Code":null,
               "allocationCustom1Code":"",
               "allocationCustom2Code":"",
               "allocationCustom3Code":"",
               "allocationCustom4Code":null,
               "allocationCustom5Code":null,
               "allocationPercentage":100.00000000,
               "allocationCustom1Value":null,
               "allocationCustom2Value":null,
               "allocationCustom3Value":null,
               "allocationCustom4Value":null,
               "allocationCustom5Value":null,
               "allocationCustom6Value":null,
               "allocationCustom7Value":null,
               "allocationCustom8Value":null,
               "allocationCustom9Value":null,
               "allocationCustom10Value":null,
               "allocationCustom11Value":null,
               "allocationCustom12Value":null,
               "allocationCustom13Value":null,
               "allocationCustom14Value":null,
               "allocationCustom15Value":null,
               "allocationCustom16Value":null,
               "allocationCustom17Value":null,
               "allocationCustom18Value":null,
               "allocationCustom19Value":null,
               "allocationCustom20Value":null,
               "allocationKey":158
            }
         ],
         "receiptNumbers":[

         ],
         "expenseTypeName":"Material",
         "poLineNumber":null,
         "externalLineItemId":null,
         "expenseTypeCode":"2000   ",
         "lineItemPurchaseOrderNumber":null,
         "lineItemCode":null,
         "lineItemDeliverySlipNumber":null,
         "lineItemUnitPrice":50.00000000,
         "lineItemSequenceOrder":1,
         "lineItemQuantity":1.00000000,
         "lineItemCustom1Value":null,
         "lineItemCustom2Value":null,
         "lineItemCustom3Value":null,
         "lineItemCustom4Value":null,
         "lineItemCustom5Value":null,
         "lineItemCustom6Value":null,
         "lineItemCustom7Value":null,
         "lineItemCustom8Value":null,
         "lineItemCustom9Value":null,
         "lineItemCustom10Value":null,
         "lineItemCustom11Value":null,
         "lineItemCustom12Value":null,
         "lineItemCustom13Value":null,
         "lineItemCustom14Value":null,
         "lineItemCustom15Value":null,
         "lineItemCustom16Value":null,
         "lineItemCustom17Value":null,
         "lineItemCustom18Value":null,
         "lineItemCustom19Value":null,
         "lineItemCustom20Value":null,
         "lineItemCustom1Code":null,
         "lineItemCustom2Code":null,
         "lineItemCustom3Code":null,
         "lineItemCustom4Code":null,
         "lineItemCustom5Code":null,
         "lineItemCustom6Code":null,
         "lineItemCustom7Code":null,
         "lineItemCustom8Code":null,
         "lineItemCustom9Code":null,
         "lineItemCustom10Code":null,
         "lineItemCustom11Code":null,
         "lineItemCustom12Code":null,
         "lineItemCustom13Code":null,
         "lineItemCustom14Code":null,
         "lineItemCustom15Code":null,
         "lineItemCustom16Code":null,
         "lineItemCustom17Code":null,
         "lineItemCustom18Code":null,
         "lineItemCustom19Code":null,
         "lineItemCustom20Code":null,
         "lineItemDescription":"Merchandise"
      }
   ]
}

Cash Advance

{
   "employeeData": {
      "employeeFirstName": "FirstName",
      "employeeLastName": "LastName",
      "employeeId": "12345ID",
      "employeeMI": null,
      "employeeOrgUnit5Code": null,
      "employeeOrgUnit6Code": null,
      "employeeOrgUnit1Value": null,
      "employeeOrgUnit2Value": null,
      "employeeOrgUnit3Value": null,
      "employeeOrgUnit4Value": null,
      "employeeOrgUnit5Value": null,
      "employeeOrgUnit6Value": null,
      "employeeCustom1Code": null,
      "employeeCustom2Code": null,
      "employeeCustom3Code": null,
      "employeeCustom4Code": "001",
      "employeeCustom5Code": "ABUFG",
      "employeeCustom6Code": "2567",
      "employeeCustom7Code": null,
      "employeeCustom8Code": null,
      "employeeCustom9Code": null,
      "employeeCustom10Code": null,
      "employeeCustom11Code": null,
      "employeeCustom13Value": null,
      "employeeCustom14Value": null,
      "employeeCustom15Value": null,
      "employeeCustom16Value": null,
      "employeeCustom17Value": null,
      "employeeCustom18Value": null,
      "employeeCustom19Value": null,
      "employeeCustom20Value": null,
      "employeeCustom21Value": "US Group",
      "employeeCustom12Code": null,
      "employeeCustom13Code": null,
      "employeeCustom14Code": null,
      "employeeCustom15Code": null,
      "employeeCustom16Code": "N",
      "employeeCustom17Code": null,
      "employeeCustom18Code": null,
      "employeeCustom19Code": null,
      "employeeCustom20Code": null,
      "employeeCustom21Code": "US Group",
      "employeeCustom1Value": null,
      "employeeCustom2Value": null,
      "employeeCustom3Value": null,
      "employeeCustom4Value": "US Inc.",
      "employeeCustom5Value": "US Publishing",
      "employeeCustom6Value": "Operations",
      "employeeCustom7Value": null,
      "employeeCustom8Value": null,
      "employeeCustom9Value": null,
      "employeeCustom10Value": null,
      "employeeCustom11Value": null,
      "employeeCustom12Value": null,
      "employeeOrgUnit1Code": null,
      "employeeOrgUnit2Code": null,
      "employeeOrgUnit3Code": null,
      "employeeOrgUnit4Code": null
   },
   "cashAdvanceData": {
      "locationName": null,
      "exchangeRate": 1,
      "countryCode": null,
      "currencyAlphaCode": "USD",
      "cashAdvanceId": "FE884EE31617CF4CABE36C7FC44512A1",
      "clearingAccountCode": null,
      "purpose": null,
      "paymentMethod": 0,
      "requestAmount": 150,
      "requestDate": "2018-03-03T02:16:51.363Z",
      "issuedDate": "2018-03-06T03:54:36.993Z",
      "isTest": "N",
      "countrySubCode": null,
      "requestedDisbursementDate": null,
      "travelStartDate": null,
      "travelEndDate": null,
      "currencyNumCode": "840",
      "expensePayIndicator": "N",
      "employeeCurrencyAlphaCode": "USD",
      "cardAccountID": null,
      "cardTransactionID": null,
      "cardTransactionAmount": null,
      "cardTransactionCurrency": null,
      "cardTransactionPostedAmount": null,
      "cardTransactionPostedCurrency": null,
      "transactionType": 1,
      "name": "Cash Advance Testing 3"
   },
   "journalData": [
      {
         "accountCode": "12345",
         "amount": 150,
         "payee": "EMPL",
         "debitOrCredit": "DR",
         "payer": "COMP",
         "paymentCode": "Cash"
      }
   ]
}

IMAGE

Receipt Image v3

The SAP Concur Receipt Image API allows for the management of receipt images attached to expense reports, expense entries, and payment requests. You can retrieve existing images by Image ID, and upload new images to a User. This API allows you to upload images in a predefined format and size targeting a specific resource or user in SAP Concur. You can also pull images down from SAP Concur by either displaying them in the browser or downloading the image content to save locally.

Note: This API is not designed to obtain the receipt images attached to an expense report. If you are an Enterprise Partner creating integrations that are intended to obtain final-approved Expense or Invoice data, and the accompanying receipt images that substantiate those transactions you will need to use Image v1. These scenarios include, but are not limited to: ERP integrations for financial journal entry postings, VAT reclaim integrations that obtain transactions to calculate VAT reclaim, project billing integrations used to substantiate expenses billed back, etc.

Scope Usage

Name Description Endpoint
IMAGE Add or Retrieve Report and Line Item Images. GET, POST, PUT, DELETE

Retrieve a List of All Receipt Images

GET /api/v3.0/expense/receiptimages

Parameters

Name Type Format Description
offset string query Starting page offset
limit Int32 query Number of records to return (default 25)
user string query The login ID of the user. Optional. The user must have the Web Services Admin (Professional) or Can Administer (Standard) user role to use this parameter.

Retrieve a Receipt Image by ID

GET /api/v3.0/expense/receiptimages/{id}

Parameters

Name Type Format Description
id string path Required ReceiptImage ID
user string query The login ID of the user. Optional. The user must have the Web Services Admin (Professional) or Can Administer (Standard) user role to use this parameter.

Example

The above GET request produces this response:

<Image xmlns="http://www.concursolutions.com/api/image/2011/02" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <Id>sample</Id>
  <Url>https://imagingupload.concursolutions.com/file/p00884704c6o/5A789811F139BC89D9C42DDE5FEE2A655BB7C2A375E9C481FA0BE92FFF690E298F119925A5C834385C8D62AE5FC4E65AC0F53E4C7273C14A4E71D4264F104882H142570AF84FBEEEC439486FE89E44D2F?id=51253775812C4750888F2e=p00884704c6o3t=AN</Url>
</Image>

Copy and paste the URL into a browser session to render the image. This is a temporary URL.

Create a New Receipt Image

POST /api/v3.0/expense/receiptimages

Parameters

Name Type Format Description
user string query The login ID of the user. Optional. The user must have the Web Services Admin (Professional) or Can Administer (Standard) user role to use this parameter.
image file body Required Image data file

Append a Receipt Image

PUT /api/v3.0/expense/receiptimages/{id}

Parameters

Name Type Format Description
id string path Required ID of the receipt image to update
user string query The login ID of the user. Optional. The user must have the Web Services Admin (Professional) or Can Administer (Standard) user role to use this parameter.
image file body Required Image data file

Delete a Receipt Image

DELETE /api/v3.0/expense/receiptimages/{id}

Parameters

Name Type Format Description
id string path Required ID of the receipt image to delete
user string query The login ID of the user. Optional. The user must have the Web Services Admin (Professional) or Can Administer (Standard) user role to use this parameter.

Schema

Receipt Images

Name Type Format Description
Items Array Receipt Image The result collection.
NextPage string - The URI of the next page of results, if any.

Receipt Image

Name Type Format Description
ID string - The unique identifier of the resource.
URI string - The URI to the resource.

INSIGHTS

Latest Bookings

Gets the latest hotel and air booking for a particular user.

Version

3.0

Retrieve the latest hotel and air booking for a particular user

GET /api/v3.0/insights/latestbookings/

Parameters

Name Type Format Description
user string query The login ID of the user. The user must have the Web Services Admin (Professional) or Can Administer (Standard) user role to use this parameter.

Schema

Latest Booking

Name Type Format Description
Airlines array Airline The latest booked airline segments.
Hotel Hotel - The latest booked hotel segment.

Airline

Name Type Format Description
BookingClass string - The booking class of the latest booked airline segment.
Code string - The airline code of the latest booked airline segment.

Hotel

Name Type Format Description
Location string - The IATA airport code of the location of the latest booked hotel segment.
StarRating Int32 - The star rating of the latest booked hotel segment. Possible values are from 0 - 5. Values 1 - 5 are mapped to the Northstar standard. If the value is 0, the star rating could not be found.

Opportunities

Retrieves a collection of opportunities for a specified trip or for all trips that fall within a date range.

Version

3.0

GET https://www.concursolutions.com/api/v3.0/insights/opportunities

Parameters

Name Type Format Description
tripId string query The trip id
opportunityType string query Comma seperated list of opportunities (Hotel, Car, Air, Rail, Taxi and Service) to get. Do not specify any values to get all opportunities
fromUtc DateTime query The From date in UTC for the date range
toUtc DateTime query The To date in UTC for the date range

Schema

Opportunities

Name Type Format Description
Items Array Opportunity The result collection.
NextPage string - The URI of the next page of results, if any.

Opportunity

Name Type Format Description
EndCityCode string - The city code of the destination city where the opportunity is offered
EndDateLocal DateTime - The local end date of the location where the opportunity is offered
EndPostalCode string - The postal code of the destination location where the opportunity is offered
ID string - The unique identifier of the resource.
IsActive boolean - Indicates that the opportunity is currently active
StartCityCode string - The city code of the originating city where the opportunity is offered
StartDateLocal DateTime - The local start date of the location where the opportunity is offered
StartPostalCode string - The postal code of the originating location where the opportunity is offered
TripId string - The trip id of the associated itinerary
Type string - The type of opportunity. Possible values: 'Hotel', 'Car', 'Air', 'Rail', 'Taxi' or 'Service'
URI string - The URI to the resource.

INVOICE

Retrieve Invoice Digests v3

Version

3.0

Retrieves All Invoice Digests Based On the Search Criteria

GET /api/v3.0/invoice/paymentrequestdigests

Parameters

Name Type Format Description
offset string query The start of the page offset.
limit Int32 query The number of records to return. Default: 1,000
approvalStatus string query A code representing an Invoice Approval Status. Use GET /invoice/localizeddata to get the available approval status codes.
paymentStatus string query A code representing an Invoice Payment Status. Use GET /invoice/localizeddata to get the available payment status codes
vendorInvoiceNumber string query Vendor invoice number tied to the invoice.
createDateBefore DateTime YYYY-MM-DD The invoice create date is before this date.
createDateAfter DateTime YYYY-MM-DD The invoice create date is after this date.
userDefinedDateBefore DateTime YYYY-MM-DD The invoice user defined date is before this date.
userDefinedDateAfter DateTime YYYY-MM-DD The invoice user defined date is after this date.
submitDateBefore DateTime YYYY-MM-DD The invoice submit date is before this date.
submitDateAfter DateTime YYYY-MM-DD The invoice submit date is after this date.
paidDateBefore DateTime YYYY-MM-DD The invoice paid date is before this date.
paidDateAfter DateTime YYYY-MM-DD The invoice paid date is after this date.
payMethodType string query Payment method type tied to an Invoice. Use GET /invoice/localizeddata to get the available Pay Method types.
lastModifiedDateBefore DateTime YYYY-MM-DD The invoice last modified date is before this date.
lastModifiedDateAfter DateTime YYYY-MM-DD The invoice last modified date is after this date.
extractedDateBefore DateTime YYYY-MM-DD The invoice extracted date is before this date.
extractedDateAfter DateTime YYYY-MM-DD The invoice extracted date is after this date.

Retrieves an Invoice Digest Based On ID

GET /api/v3.0/invoice/paymentrequestdigests/{id}

Parameters

Name Type Format Description
id string path Required The invoice ID

Schema

Payment Request Digests

Name Type Format Description
Items Array Payment Request Digest The result collection.
NextPage string - The URI of the next page of results, if any.
PaymentRequestDigest Array Payment Request Digest -
TotalCount Int32 - -

Payment Request Digest

Name Type Format Description
ApprovalStatusCode string - Required A code indicating the invoice's approval status.
CreateDate string - The date the invoice was created.
CurrencyCode string - The 3-letter ISO 4217 currency code for the invoice currency. Examples: USD - US dollars; BRL - Brazilian real; CAD - Canadian dollar; CHF - Swiss franc; EUR - Euro; GBO - Pound sterling; HKD - Hong Kong dollar; INR - Indian rupee; MXN - Mexican peso; NOK - Norwegian krone; SEK - Swedish krona.
ID string - The unique identifier of the resource.
InvoiceNumber string - The invoice number of the Invoice.
IsDeleted boolean - A true/false value which indicates whether the invoice has been deleted. (Deleted invoices are retained in the system for historical purposes.).
OwnerLoginID string - The login ID of the Invoice owner.
OwnerName string - The name of the Invoice owner.
PaidDate string - The date when all journal entries in the invoice were integrated with or extracted to the financial system.
PaymentRequestId string - Required The unique identifier of the Invoice summarized in this digest.
PaymentRequestUri string - Required URI of the Invoice summarized in this digest.
PaymentStatusCode string - Required A code indicating the invoice's payment status.
Total string - The total amount of the invoice.
URI string - The URI to the resource.
UserDefinedDate string - The invoice date as assigned by the user.
VendorName string - Required The name of the vendor.
PaymentMethod string - Payment method type tied to an Invoice.
LastModifiedDate string - The date the invoice was last modified.
ExtractedDate string - The date the invoice was extracted.

Invoice v3

Version

3.0

Retrieve an Invoice

GET /api/v3.0/invoice/paymentrequest/{id}

Parameters

Name Type Format Description
id string path Required Invoice ID.

Create a New Invoice

POST /api/v3.0/invoice/paymentrequest

Payload

Update an Invoice

PUT /api/v3.0/invoice/paymentrequest

Payload

Schema

Payment Request

Name Type Format Description
AmountWithoutVat string - The net amount of the invoice (excluding VAT).
BuyerCostCenter string - The company defined center responsible for the Invoice.
CheckNumber string - Check number of the payment made to the vendor.
CompanyBillToAddressCode string - The code which identifies the company location to which the vendor billed the invoice.
CompanyShipToAddressCode string - The code which identifies the company location to which the vendor shipped items listed in the invoice.
CountryCode string - Required The country code.
CurrencyCode string - The 3-letter ISO 4217 currency code for the invoice currency. Examples: USD - US dollars; BRL - Brazilian real; CAD - Canadian dollar; CHF - Swiss franc; EUR - Euro; GBO - Pound sterling; HKD - Hong Kong dollar; INR - Indian rupee; MXN - Mexican peso; NOK - Norwegian krone; SEK - Swedish krona.
Custom1 through Custom24 string - The details from the Custom fields. These may not have data, depending on configuration.
DataSource string - A code which indicates the method used to created the Invoice. Use GET /invoice/localizeddata to translate the code into text.
DeliverySlipNumber string - The delivery slip number associated with receiving receipt.
Description string - User entered description of the Invoice.
DiscountPercentage string - The discount from the supplier if the discount terms are met.
DiscountTerms string - The NET discount terms with a supplier when discounts apply.
EmployeeEmailAddress string - The email address of the employee to whom the invoice should be assigned. Not evaluated if EmployeeLoginId or EmployeeId match an employee. This value is required if none of the following are provided: LedgerCode; EmployeeLoginId, EmployeeId; PurchaseOrderNumber; ExternalPolicyId.
EmployeeId string - The company ID of the employee to whom the invoice should be assigned. Has precedence over EmployeeEmail; not evaluated if EmployeeLoginId matches an employee. This value is required if none of the following are provided: LedgerCode; EmployeeLoginId; EmployeeEmail; PurchaseOrderNumber; ExternalPolicyId.
EmployeeLoginId string - The login ID of the employee to whom the invoice should be assigned. Has precedence over EmployeeId and EmployeeEmail. This value is required if none of the following are provided: LedgerCode; EmployeeId; EmployeeEmail; PurchaseOrderNumber; ExternalPolicyId.
ExternalPolicyId string - The external policy ID of the Invoice. This value is required if none of the following are provided: LedgerCode; EmployeeLoginId, EmployeeId; EmployeeEmail; PurchaseOrderNumber.
InvoiceAmount string - Required User-entered value representing the total invoice amount, used to calculate amount remaining on the line item page.
InvoiceDate string - The date the vendor issued the Invoice.
InvoiceNumber string - The Invoice Number from the vendor for the Invoice.
InvoiceReceivedDate string - The date on which the invoice was received.
IsEmergencyCheckRun string - Is an emergency check run required (Y/N).
IsInvoiceConfirmed boolean - Indicates if the Invoice is confirmed or in a different status Supported values: true, false
LedgerCode string - A code which indicates which company journal the Invoice is assigned to. Use GET /invoice/localizeddata to obtain valid codes. This value is required if none of the following are provided: EmployeeLoginId; EmployeeId; EmployeeEmail; PurchaseOrderNumber; ExternalPolicyId.
LineItems array LineItem The details of the Core Payment Request Line Item Identity Fields.
Name string - Required The Invoice name.
NotesToVendor string - Information from the customer to the vendor for special requests or handling for the ordered good or service.
OB10BuyerId string - A unique buyer account on the OB10 network.
OB10TransactionId string - Unique Identifier for the Invoice transaction (generated by OB10).
OrgUnit1 string - The details from the Organization Unit fields. These may not have data, depending on configuration.
OrgUnit2 string - The details from the Organization Unit fields. These may not have data, depending on configuration.
OrgUnit3 string - The details from the Organization Unit fields. These may not have data, depending on configuration.
OrgUnit4 string - The details from the Organization Unit fields. These may not have data, depending on configuration.
OrgUnit5 string - The details from the Organization Unit fields. These may not have data, depending on configuration.
OrgUnit6 string - The details from the Organization Unit fields. These may not have data, depending on configuration.
PaymentAdjustmentNotes string - Notes to the vendor regarding the amount paid (underpayment due to damages, for example).
PaymentAmount string - Represents the amount of the payment that will be/has been made for the Invoice.
PaymentDueDate string - The date the vendor needs to be paid by.
PaymentTermsDays string - This number, along with type of payment terms (example: NET), determine when the invoice is expected to be paid.
ProvincialTaxId string - The Vendor Provincial Tax ID.
PurchaseOrderNumber string - The ID of the Purchase Order to which the Invoice should be matched. This value is required if none of the following are provided: LedgerCode; EmployeeLoginId, EmployeeId, EmployeeEmail, ExternalPolicyId.
ReceiptConfirmationType string - A code which indicates the receipt confirmation type for this Invoice (Invoice Confirmation, for example). Use GET /invoice/localizeddata to translate the code into text.
ShippingAmount string - The value for the Shipping Amount header field.
TaxAmount string - The value for the Tax Amount header field.
VatAmountOne string - The amount of VAT included in the invoice total (first of two VAT amount fields available).
VatAmountTwo string - The amount of VAT included in the invoice total (second of two VAT amount fields available).
VatRateOne string - The VAT rate applied to the net invoice total (should relate to the first VAT amount field).
VatRateTwo string - The VAT rate applied to the net invoice total (should relate to the second VAT amount field).
VendorRemitToIdentifier object VendorRemitToIdentifier Required Used to identify the vendor location for payment remittance. At a minimum, the VendorCode or the combination of (VendorName, Address1, and PostalCode) are required. Use of as many fields as possible is encouraged to ensure a single vendor can be identified. If more than one vendor matches the information provided, the Invoice creation attempt will fail.
VendorShipFromAddressCode string - The code which identifies the location from which the vendor shipped items listed in the invoice.
VendorTaxId string - The Vendor Tax ID.

LineItem

Name Type Format Description
Allocations array Allocation The details of the Invoice allocation fields.
AmountWithoutVat string - The net amount of the line item (excluding VAT).
Custom1 through Custom20 string - The details from the Custom fields. These may not have data, depending on configuration.
Description string - Brief overview of the good or service ordered.
ExpenseTypeCode string - A code which indicates the Expense Type for the Line Item.
ItemCode string - Represents the item code (the unique code a vendor assigns to a good or code a vendor assigns to a good or service to identify it).
MatchedPurchaseOrderReceipts array MatchedPurchaseOrderReceipt The details of the Matched Purchase Order Receipts Identity Fields (if any).
PurchaseOrderNumber string - Purchase Order that is associated to the Line Item .
Quantity string - Total number of goods or services ordered.
ShipFromPostalCode string - The postal code the good or service was shipped from.
ShipToPostalCode string - The postal code the good or service will be shipped to.
SupplierPartId string - The unique identifier provided by the supplier that is associated with the good or service.
Tax string - The tax associated with the line item.
TotalPrice string - The total amount of the line item.
UnitOfMeasure string - The code for the measurement unit used to quantify the good or service. Use GET /invoice/localizeddata to look up codes and descriptions.
UnitPrice string - The cost for a single unit of the line item good or service.
VatAmount string - The amount of VAT included in the line item total.
VatRate string - The VAT rate applied to the net line item total.

Allocation

Name Type Format Description
Custom1 through Custom7 string - The details from the Custom fields. These may not have data, depending on configuration.
Custom8 string - A value that can be applied to a custom field 8 that is part of the allocation form.
Custom9 string - A value that can be applied to a custom field 9 that is part of the allocation form.
Custom10 string - A value that can be applied to a custom field 10 that is part of the allocation form.
Custom11 through Custom20 string - The details from the Custom fields. These may not have data, depending on configuration.
Percentage string - Required The percentage of the Request Line Item that the individual allocation record. All Allocations associated to a given Line Item should add up to 100.

MatchedPurchaseOrderReceipt

Name Type Format Description
GoodsReceiptNumber string - The identifier of the purchase order goods receipt number to which the Invoice line item is matched.

VendorRemitToIdentifier

Name Type Format Description
Address1 string - Line 1 of the street address.
AddressCode string - The code which identifies a particular vendor location.
Name string - The name of the vendor.
PostalCode string - The postal / zip code.
VendorCode string - The code which identifies a particular vendor.

Purchase Order Receipt v3

Purchase order receipts are records that indicate purchase order lines were completed and received. This API provides methods to create a new purchase order receipt, and retrieve, update, or delete an existing purchase order receipt.

Version

3.0

Create a new purchase order receipt

POST /api/v3.0/invoice/purchaseorderreceipts

Creates purchase order receipt, associates it to purchase order line item, and returns update status.

Parameters

Name Type Format Description
purchaseOrderReceipt - body The details of the purchase order receipt.

Input

Schema

{
  "Deleted": "false",
  "DeliverySlipNumber": "DSN1",
  "GoodsReceiptNumber": "RCPT1",
  "ID": "1000001",
  "LineItemExternalID": "LN000001",
  "PurchaseOrderNumber": "PO12345",
  "ReceivedDate": "2018-09-15 00:00:00.0",
  "ReceivedQuantity": "14.5",
  "UnitOfMeasureCode": "DA",
  "URI": "string",
  "Version": "2.0"
}

Response

Response schema

Update purchase order line item with receipt information

PUT /api/v3.0/invoice/purchaseorderreceipts

Parameters

Name Type Format Description
purchaseOrderReceipt - body Purchase order receipt information.

Input

Receipt schema

Response

Response schema

Get existing purchase order receipt

GET /api/v3.0/invoice/purchaseorderreceipts?purchaseOrderNumber=PO1&lineItemExternalID=L1&goodsReceiptNumber=GRN1

Parameters

Name Type Format Description
purchaseOrderNumber string {purchaseOrderNumber} The purchase order number.
lineItemExternalID string {lineItemExternalID} A customer-supplied value that uniquely identifies the line item within the purchase order.
goodsReceiptNumber string {goodsReceiptNumber} Goods receipt number for a purchase order line item receipt.

Input

None.

Response

Schema

Delete existing purchase order receipt

DELETE /api/v3.0/invoice/purchaseorderreceipts?purchaseOrderNumber=PO1&lineItemExternalID=L1&goodsReceiptNumber=GRN1

Parameters

Name Type Format Description
purchaseOrderNumber string {purchaseOrderNumber} The purchase order number.
lineItemExternalID string {lineItemExternalID} A customer-supplied value that uniquely identifies the line item within the purchase order.
goodsReceiptNumber string {goodsReceiptNumber} Goods receipt number for a purchase order line item receipt.

Input

None.

Response

Response schema

Response schema

Name Type Format Description
ErrorCode string - A code that indicates why the purchase order receipt was not processed successfully.
ErrorMessage string - A description of the error.
FieldCode string - A code that indicates which field caused an issue. This code typically appears only when a field is being validated against a field of a form type.
LineItemExternalID string - The external ID of a line item that caused an error.
Message string - Message of request result.
PurchaseOrderNumber string - The purchase order number.
Status string - The result of processing the purchase order receipt. Format: SUCCESS or FAILURE

Get Purchase Order Receipt schema

Name Type Format Description
purchaseOrderReceipt array PurchaseOrderReceipt Purchase Order Receipt.
NextPage string - The URI of the next page of results, if any.
TotalCount int - Total number of receipts.
Info string - Any additional information messages. Currently a maximum of 2000 PO receipts will be returned.

Receipt schema

Name Type Format Description
Deleted boolean - Delete status of purchase order line item receipt.
DeliverySlipNumber string - Delivery slip number for a purchase order line item receipt.
GoodsReceiptNumber string - Goods receipt number for a purchase order line item receipt.
ID string - The unique identifier of the resource.
LineItemExternalID string - Required A customer-supplied value that uniquely identifies the line item within the purchase order.
PurchaseOrderNumber string - Required The purchase order number.
ReceivedDate string - The date the line item was received. Format: YYYY-MM-DD
ReceivedQuantity string - The number of items that were received.
UnitOfMeasureCode string - Unit of measure code for a purchase order line item receipt.
URI string - The URI to the resource.
Version string - The version of purchase order line item receipt. Use Version 2.0 here unless doing receipt confirmation only.

Error codes

The Purchase Order Receipt API’s error responses

Code Description
1000 The PO number is missing or invalid.
1001 The External ID is missing or invalid.
1002 The Is Received is invalid. It must be either empty, Y/N, or y/n.
1003 The Received Quantity is invalid. It must be either empty or numeric.
1004 The Received Date is invalid. It must be either empty or date formatted YYYY-MM-DD.
1005 The Unit Of Measure code is invalid. It must be either empty or Valid with less than 10 chars in length.
1006 The Received Quantity is invalid, for Receipt Type WQTY on Purchase Order, Quantity is required. Sorry.
1007 The field is not part of the form
1008 The value exceeds the maximum length allowed for the field.
1009 The value is the wrong data type for the field.
1011 The invalid value expression.
9999 An unexpected error occurred.
10010 The required field is missing.

Purchase Orders v3

The Purchase Orders API gives SAP Concur clients the ability to leverage external data to create and update approved purchase orders. Clients can build a direct connection to the Purchase Orders API which will create purchase orders for invoices to be associated to. It also allows clients to update created purchase orders when orders change, need to be closed, or identify and resolve matching exceptions on PO invoices.

Limitations: This API is not available in the China Data center. This API is only available for direct integrations with an existing SAP Concur client. This API can only be used to create new purchase requests and get the details of the created purchase request. This API cannot update, edit, or delete purchase requests. All edits or processing of the purchase request after it is sent to SAP Concur and created must be done in SAP Concur.

Products and Editions

Scope Usage

Required Scopes:

Name Description Endpoint
INVPO Create, update, and retrieve purchase orders. POST, PUT, GET

Dependencies

SAP Concur clients must purchase Concur Invoice, Concur Purchase Order, and Concur Web Services in order to use this API. Concur Invoice with Concur Purchase Order must be configured before using this API.

To create purchase orders, you need to supply a Vendor Code and Vendor Address Code. You can access Vendor Manager in Concur Invoice to see these values. If you need to get this data from SAP Concur using web services, you can use the Vendor v3 API.

If your purchase order form in SAP Concur has required custom fields that are tied to lists, you will need to supply the Item Code for the list items. You can access List Management in SAP Concur to see your list items and list item codes. If you need to get this data from SAP Concur using web services, you can use the List Item v3 API to retrieve the Level1Code value for the list items.

Access Token Usage

This API will work with both company or user access tokens. A company access token is required if the integration will create purchase orders for multiple requestors. Using a user access token to create purchase order results in the purchase order being assigned to the user that generated the user access token, not the user set in the payload. A user access token can be used for testing purposes.

Create a New Purchase Order

POST /api/v3.0/invoice/purchaseorders

Create or update a Purchase Order. Batch processing is not available using the Purchase Order API. Please use Import Jobs for batch updates.

Payload

Example

{
  "BillToAddress": {
    "Address1": "add1",
    "Address2": "add2",
    "Address3": "add3",
    "City": "city",
    "CountryCode": "US",
    "ExternalID": "billtoapi",
    "Name": "billto",
    "PostalCode": "55426",
    "StateProvince": "MN"
  },
  "CurrencyCode": "USD",
  "OrderDate":"2011-08-12T20:17:46.384Z",
  "ID": "API101",
  "IsTest": "false",
  "IsChangeOrder": "false",
  "LedgerCode": "23",
  "LineItem": [
    {
      "Allocation": [
        {
          "Amount": "106.74",
          "Percentage":"100.00000000",
          "GrossAmount":"106.74"
        }
      ],
      "CreateDate": "2019-12-13 20:00:37.0",
      "Description": "line 1",
      "ExpenseType": "Advertising",
      "ExternalID": "API100line1",
      "IsReceiptRequired": "true",
      "LineNumber": "1",
      "PurchaseOrderReceiptType": "WQTY",
      "Quantity": "1.00",
      "UnitOfMeasureCode":"DA",
      "UnitPrice": "106.74"
    }
  ],
  "Name": "poName",
  "PolicyExternalID": "PO",
  "PurchaseOrderNumber": "API101",
  "PurchaseRequestNumber": "100001",
  "RequestedBy": "Deo, John",
  "Shipping": "0.00000000",
  "ShipToAddress": {
    "Address1": "add1",
    "Address2": "add2",
    "Address3": "add3",    
    "City": "cityship",
    "CountryCode": "US",
    "ExternalID": "Shiptoapi",
    "Name": "shiptoapi",
    "PostalCode": "55426",
    "StateProvince": "MN"
  },
  "Status": "Transmitted",
  "Tax": "0.00000000",
  "URI": "http://www.concursolutions.com/api/v3.0/invoice/purchaseorders/purchaseorders/API101",
  "VendorCode": "VEN1",
  "VendorAddressCode": "VEN1ADDR1"
}

Response

Update Purchase Order Line Item With Receipt Information

PUT /api/v3.0/invoice/purchaseorderreceipts

Payload

Response

Update an Existing Purchase Order

PUT /api/v3.0/invoice/purchaseorders

Payload

Response

Get an Existing Purchase Order

GET /api/v3.0/invoice/purchaseorders/{id}

Parameters

Name Type Format Description
id string {id} The identifier for the purchase order.

Input

None

Response

Schema

purchaseOrder

Name Type Format Description
AmountWithoutVat string - The net amount of the purchase order (excluding VAT).
BillToAddress object BillToAddress Required The customer's billing address, which is where the vendor should send the bill.
CurrencyCode string - Required The 3-letter ISO 4217 currency code of the currency that is associated with the purchase order.
Custom1 through Custom24 string - A value that can be applied to a custom field that is part of the purchase order header form.
Description string - A description of the purchase order.
DiscountPercentage string - The discount from the vendor, if the discount terms are met.
DiscountTerms string - The net discount terms that the vendor offers, when discounts apply.
ID string - The unique identifier of the resource.
IsTest string true / false If the purchase order is a test.
IsChangeOrder string true / false If the purchase order has a change order or not.
LedgerCode string - A code which indicates which company journal the Purchase Order is assigned to.
LineItem array LineItem Required The line items in a purchase order.
Name string - Required A name for the purchase order.
NeededByDate string YYYY-MM-DD The date by which the purchase order must be fulfilled.
OrderDate string YYYY-MM-DD Required The date when goods were ordered.
PaymentTerms string - The net payment terms that have been set up with a vendor.
PolicyExternalID string - Required The external identifier of the policy that should be associated with the purchase order. The external Id is a property of the policy configuration screen. Clients will need to get these ID’s from the Implementation team if using professional version. For standard version the value is always PO.
PoVendorTaxId string - The vendor tax ID.
ProvincialTaxId string - The vendor provincial tax ID.
PurchaseOrderNumber string - The purchase order number.
PurchaseRequestNumber string - The related purchase request number that generated the purchase order.
ReceiptType string - The purchase order receipt type (Deprecated). Use the PurchaseOrderReceiptType at line item level instead.
RequestedBy string - The person who requests the goods in the purchase order.
RequestedDeliveryDate string YYYY-MM-DD The date the purchase order instructed the vendor to deliver the goods.
Shipping string - The total shipping cost for the purchase order.
ShippingDescription string - A description of how the goods in the purchase order will ship. For example, via FedEx.
ShippingMethodKey string - A code that represents the shipping method used by the vendor. Maximum length: 10 characters
ShippingTermsKey string - A code that represents the shipping terms that the vendor offers. Maximum length: 10 characters
ShipToAddress object ShipToAddress Required The customer's shipping address, which is where the vendor should ship the goods.
Status string - The current status of the purchase order. Default: Transmitted. Supported values: Closed, Transmitted
Tax string - The total tax for the purchase order.
URI string - The URI to the resource.
VatAmountOne string - This field has not been implemented by Purchase Request yet. Any data in this field will be ignored.
VatAmountTwo string - This field has not been implemented by Purchase Request yet. Any data in this field will be ignored.
VatRateOne string - This field has not been implemented by Purchase Request yet. Any data in this field will be ignored.
VatRateTwo string - This field has not been implemented by Purchase Request yet. Any data in this field will be ignored.
VendorAccountNumber string - The vendor account number.
VendorAddressCode string - Required The code that identifies the vendor's remit address for the purchase order.
VendorCode string - Required The code that identifies the vendor for the purchase order.

BillToAddress

Name Type Format Description
Address1 string - Required Address line 1 of the billing address.
Address2 string - Address line 2 of the billing address.
Address3 string - Address line 3 of the billing address.
City string - Required The city of the billing address.
CountryCode string - Required The code of the country for the billing address.
ExternalID string - Required A unique value supplied by the customer to identify a particular billing address.
Name string - An optional name that can be given to the billing address.
PostalCode string - Required The postal code of the billing address.
StateProvince string - Required The state or province of the billing address.

LineItem

Name Type Format Description
AccountCode string - The account code of the line item. A value must be supplied for either ExpenseType or AccountCode, but not both. This field is required if an ExpenseType value is not supplied.
Allocation array Allocation A list of the allocations that are associated with the line item. Allocation elements can be repeated within the same line items to represent multiple allocations.
AmountWithoutVat string - The net amount of the line item (excluding VAT).
CreateDate string YYYY-MM-DD The date the line item was created.
Custom1 through Custom20 string - A value that can be applied to a custom field 1 that is part of the purchase order line item form.
Description string - A description of the line item.
ExpenseType string - The expense type of the line item. A value must be supplied for either ExpenseType or AccountCode, but not both. This field is required if an AccountCode value is not supplied.
ExternalID string - Required A customer-supplied value that uniquely identifies the line item within the purchase order.
IsReceiptRequired string true / false Indicates whether the line item requires a receipt.
LineNumber string - Required The line item number within the purchase order.
Quantity string - Required The quantity associated with the line item.
PurchaseOrderReceiptType string - Purchase order ReceiptType of the line item. If you are using Concur Receiving and need to enter Goods Receipts against the resulting PO lines use QUANTITY_RECEIPT. Default: NONE. Supported values: QUANTITY_RECEIPT, NONE
RequestedBy string - The person who requests the goods in the line item of the purchase order.
RequestedDeliveryDate string YYYY-MM-DD The date the line item of the purchase order instructed the vendor to deliver the goods.
SupplierPartID string - Any number that might help to identify the line item. This could be a value such as the vendor's part number or even the manufacturer number.
Tax string - Any tax that is associated with the line item.
UnitOfMeasureCode string - The unit of measure code of the line item.
UnitPrice string - Required The price of each item of the line item.
VatAmount string - This field has not been implemented by Purchase Request yet. Any data in this field will be ignored.
VatRate string - This field has not been implemented by Purchase Request yet. Any data in this field will be ignored.

Allocation

Name Type Format Description
Amount string - Required The total amount of the allocation.
Custom1 through Custom20 string - A value that can be applied to a custom field 1 that is part of the allocation form.
GrossAmount string - Required The allocation gross amount.
Percentage string - Required The allocation percentage.

ShipToAddress

Name Type Format Description
Address1 string - Required Address line 1 of the shipping address.
Address2 string - Address line 2 of the shipping address.
Address3 string - Address line 3 of the shipping address.
City string - Required The city of the shipping address.
CountryCode string - Required The code of the country for the shipping address.
ExternalID string - Required A unique value supplied by the customer to identify a particular shipping address.
Name string - An optional name that can be given to the shipping address.
PostalCode string - Required The postal code of the shipping address.
StateProvince string - Required The state or province of the shipping address.

Response Schema

Name Type Format Description
ErrorCode string - A code that indicates why the purchase order was not processed successfully.
ErrorMessage string - A description of the error.
FieldCode string - A code that indicates which field caused an issue. This code typically appears only when a field is being validated against a field of a form type. Format: LEVEL CODE. The possible levels are: Header, ShipTo, BillTo, LineItem, Allocation.
LineItemExternalID string - The external ID of a line item that caused an error. If the error is related to an allocation, this field indicates the external ID of the line item that the allocation is associated with, and also indicates the allocation that caused of the error.
Message string -
PurchaseOrderNumber string - The purchase order number.
Status string SUCCESS / FAILURE The result of processing the purchase order.

Receipt Schema

Name Type Format Description
IsReceived string - Required Indicates whether the line item was received.
LineItemExternalID string - Required A customer-supplied value that uniquely identifies the line item within the purchase order.
PurchaseOrderNumber string - Required The purchase order number.
ReceivedDate string YYYY-MM-DD The date the line item was received.
ReceivedQuantity string - The number of items that were received.

Error Codes

The web service will not return a 4xx HTTP response code for a batch operation even when every item in the batch failed to be created, updated or deleted. The client must inspect the response to look for warnings or errors with individual batch items.

Code Description
1000 The PO number is missing or invalid.
2000 There was no vendor found for the supplied Vendor Code and Vendor Address Code.
3000 The Currency Code is missing or invalid.
4000 There was no policy found matching the supplied External Id.
4001 The policy does not support purchase orders.
4002 The policy cannot be changed on the purchase order.
5000 The purchase order does not contain any line items.
5001 The line item must contain expense type or account code, but not both.
5002 The line item expense type is invalid.
5003 The line item account code is invalid.
5004 The line item tax and unit price must both match positive or negative.
5500 The line item contains an allocation, but no allocation form is defined.
5501 The line item allocation amounts exceed the line item total.
5502 The distribution amounts for a line item must match the line item amount positive or negative.
5503 The distribution amounts for a line item cannot be zero.
5600 The external id for the line item is not unique across the purchase order.
6000 The Ship To Address is missing or invalid.
6001 The Bill To Address is missing or invalid.
8000 A required field is missing.
8001 A field’s value exceeds the maximum length allowed.
8002 A field’s value is not the correct data type.
8003 A field’s value is an invalid list item.
8004 A field’s value is an invalid connected list item.
8005 The Country Code is missing or invalid.
8006 A value was supplied for a field that is not part of the form.
9999 An unexpected error occurred.

Sales Tax Validation v3

Limitations: This API is only available to partners who have been granted access by SAP Concur. Access to this documentation does not provide access to the API. This API is not available in Implementation environments.

Products and Editions

Scope Usage

Name Description Endpoint
INVTV Invoice - Tax Validation GET, PUT

Dependencies

None.

Get Invoices for Calculating Tax

Retrieves invoices for calculating tax.

Scopes

INVTV - Refer to Scope Usage for full details.

Request

URI

Template
https://{datacenterURI}/api/v3.0/invoice/salestaxvalidationrequest

Parameters

Name Type Format Description
offset string query The starting point of the next set of results, after the limit specified in the limit field has been reached.
limit Int32 query The number of invoices to retrieve. Maximum value: 1,000
modifiedafter string query A parameter that can be used to limit the results to invoices modified after the specified date.

Payload

Response

Payload

Example

Request

https://us.api.concursolutions.com/api/v3.0/invoice/salestaxvalidationrequest

Response

{
    "TotalCount": 1,
    "Items": [
        {
            "RequestID": "3E6969DD15D64A349188",
            "TaxReferenceID": "9B8888FA54CA47E598081F4527A2BC50",
            "CountryCode": "US",
            "Title": "Test Request - 15 Feb",
            "PurchaseOrderNumber": null,
            "InvoiceDate": "2019-03-01 00:00:00.0",
            "StatusCode": null,
            "Status": null,
            "InvoiceAmount": "480.00000000",
            "Total": "500.00000000",
            "ShippingAmount": "0.00000000",
            "Tax": "20.00000000",
            "CalculatedTaxAmount": null,
            "CalculatedTaxRate": null,
            "CurrencyCode": "USD",
            "VendorInvoiceNumber": "99999",
            "OrgUnit1": "1",
            "OrgUnit1Value": "Best Buy",
            "OrgUnit2": "100",
            "OrgUnit2Value": "Geek Squad",
            "OrgUnit3": null,
            "OrgUnit3Value": null,
            "OrgUnit4": null,
            "OrgUnit4Value": null,
            "OrgUnit5": null,
            "OrgUnit5Value": null,
            "OrgUnit6": null,
            "OrgUnit6Value": null,
            "Custom1": null,
            "Custom1Value": null,
            "Custom2": null,
            "Custom2Value": null,
            "Custom3": null,
            "Custom3Value": null,
            "Custom4": null,
            "Custom4Value": null,
            "Custom5": null,
            "Custom5Value": null,
            "Custom6": null,
            "Custom6Value": null,
            "Custom7": null,
            "Custom7Value": null,
            "Custom8": null,
            "Custom8Value": null,
            "Custom9": null,
            "Custom9Value": null,
            "Custom10": null,
            "Custom10Value": null,
            "Custom11": null,
            "Custom11Value": null,
            "Custom12": null,
            "Custom12Value": null,
            "Custom13": null,
            "Custom13Value": null,
            "Custom14": null,
            "Custom14Value": null,
            "Custom15": null,
            "Custom15Value": null,
            "Custom16": null,
            "Custom16Value": null,
            "Custom17": null,
            "Custom17Value": null,
            "Custom18": null,
            "Custom18Value": null,
            "Custom19": null,
            "Custom19Value": null,
            "Custom20": null,
            "Custom20Value": null,
            "Custom21": null,
            "Custom21Value": null,
            "Custom22": "Default",
            "Custom22Value": "Default-Change to Client",
            "Custom23": null,
            "Custom23Value": null,
            "Custom24": null,
            "Custom24Value": null,
            "BillToAddress": {
                "ExternalID": null,
                "Name": null,
                "Address1": null,
                "Address2": null,
                "Address3": null,
                "City": null,
                "StateProvince": null,
                "State": null,
                "PostalCode": null,
                "CountryCode": null
            },
            "ShipToAddress": {
                "ExternalID": null,
                "Name": null,
                "Address1": "BTP",
                "Address2": null,
                "Address3": null,
                "City": "Bengaluru South",
                "StateProvince": null,
                "State": null,
                "PostalCode": "560093",
                "CountryCode": "IN"
            },
            "LineItem": [
                {
                    "CommodityCode": "95121513",
                    "Quantity": "1.00000000",
                    "LineItemKey": "gWo0fa6rk0zJkpaD3ZXHL8DbNaw",
                    "UnitPrice": "200.00000000",
                    "Total": "200.00000000",
                    "CountryCode": "US",
                    "CalculatedTaxAmount": null,
                    "CalculatedTaxRate": null,
                    "CurrencyCode": "USD",
                    "Allocations": {
                        "Allocation": [
                            {
                                "Custom1": "1",
                                "Custom1Value": null,
                                "Custom2": "100",
                                "Custom2Value": null,
                                "Custom3": null,
                                "Custom3Value": null,
                                "Custom4": null,
                                "Custom4Value": null,
                                "Custom5": null,
                                "Custom5Value": null,
                                "Custom6": null,
                                "Custom6Value": null,
                                "Custom7": null,
                                "Custom7Value": null,
                                "Custom8": null,
                                "Custom8Value": null,
                                "Custom9": null,
                                "Custom9Value": null,
                                "Custom10": null,
                                "Custom10Value": null,
                                "Custom11": null,
                                "Custom11Value": null,
                                "Custom12": null,
                                "Custom12Value": null,
                                "Custom13": null,
                                "Custom13Value": null,
                                "Custom14": null,
                                "Custom14Value": null,
                                "Custom15": null,
                                "Custom15Value": null,
                                "Custom16": null,
                                "Custom16Value": null,
                                "Custom17": null,
                                "Custom17Value": null,
                                "Custom18": null,
                                "Custom18Value": null,
                                "Custom19": null,
                                "Custom19Value": null,
                                "Custom20": null,
                                "Custom20Value": null,
                                "AllocationAmount": "200.00000000"
                            }
                        ]
                    },
                    "Vendor": {
                        "VendorCode": null,
                        "VendorName": "Holiday Inn",
                        "VendorAddressName": null,
                        "AddressCode": null,
                        "Address1": null,
                        "Address2": null,
                        "Address3": null,
                        "City": null,
                        "State": null,
                        "PostalCode": null,
                        "CountryCode": null
                    }
                },
                {
                    "CommodityCode": "90111501",
                    "Quantity": "1.00000000",
                    "LineItemKey": "gWo0c5$sMJswx4W0tK$pw2bwBTFtQ",
                    "UnitPrice": "280.00000000",
                    "Total": "280.00000000",
                    "CountryCode": "US",
                    "CalculatedTaxAmount": null,
                    "CalculatedTaxRate": null,
                    "CurrencyCode": "USD",
                    "Allocations": {
                        "Allocation": [
                            {
                                "Custom1": "1",
                                "Custom1Value": null,
                                "Custom2": "100",
                                "Custom2Value": null,
                                "Custom3": null,
                                "Custom3Value": null,
                                "Custom4": null,
                                "Custom4Value": null,
                                "Custom5": null,
                                "Custom5Value": null,
                                "Custom6": null,
                                "Custom6Value": null,
                                "Custom7": null,
                                "Custom7Value": null,
                                "Custom8": null,
                                "Custom8Value": null,
                                "Custom9": null,
                                "Custom9Value": null,
                                "Custom10": null,
                                "Custom10Value": null,
                                "Custom11": null,
                                "Custom11Value": null,
                                "Custom12": null,
                                "Custom12Value": null,
                                "Custom13": null,
                                "Custom13Value": null,
                                "Custom14": null,
                                "Custom14Value": null,
                                "Custom15": null,
                                "Custom15Value": null,
                                "Custom16": null,
                                "Custom16Value": null,
                                "Custom17": null,
                                "Custom17Value": null,
                                "Custom18": null,
                                "Custom18Value": null,
                                "Custom19": null,
                                "Custom19Value": null,
                                "Custom20": null,
                                "Custom20Value": null,
                                "AllocationAmount": "280.00000000"
                            }
                        ]
                    },
                    "Vendor": {
                        "VendorCode": null,
                        "VendorName": "Holiday Inn",
                        "VendorAddressName": null,
                        "AddressCode": null,
                        "Address1": null,
                        "Address2": null,
                        "Address3": null,
                        "City": null,
                        "State": null,
                        "PostalCode": null,
                        "CountryCode": null
                    }
                }
            ],
            "ID": null,
            "URI": null
        }
    ],
    "NextPage": null
}

JSON Example of an Unsuccessful Response


{
    "Error": {
        "Message": "Forbidden Request",
        "Server-Time": "2019-03-12T07:56:32",
        "Id": "65F68719-3FF5-459E-8B94-5FC93A5CD045"
    }
}

Update Invoices with a Calculated Tax Amount and Tax Rate

Updates invoices with calculated tax amount and tax rate.

Scopes

INVTV - Refer to Scope Usage for full details.

Request

URI

Template
https://{datacenterURI}//api/v3.0/invoice/salestaxvalidationrequest

Parameters

Name Type Format Description
invoice - body The tax information for the invoice that is to be updated.

Payload

Invoice

Response

Payload

Status Schema

Example

Request

{
  "CalculatedTaxAmount": "150.00",
  "CalculatedTaxRate": "0.40",
  "Comments": "Updating Calculated Tax",
  "LineItem": [
    {
      "CalculatedTaxAmount": "50.00",
      "CalculatedTaxRate": "0.05",
      "LineItemKey": "gWo0b$sLeIU2W18zqlQiELsE7TvQ"

    }
  ],

  "StatusCode": "CMPLT",
  "TaxReferenceID": "9A0F8C3EDF4040BBA94394A1A0CA6DCB"

}

Response

{
    "TaxReferenceID": "9A0F8C3EDF4040BBA94394A1A0CA6DCB",
    "Comments": null,
    "Status": "SUCCESS",
    "Type": null,
    "Code": 0,
    "Message": null,
    "Parameters": null,
    "RecordNumber": 0
}

JSON Example of an Unsuccessful Response

{
    "Message": " Status code is a required field. ERROR,CMPLT are valid values."
}

Invoices Schema

Invoices

Name Type Format Description
Items array Invoice The result collection.
NextPage string - The URI of the next page of results, if any.
TotalCount Int32 - The amount of items returned.

Invoice

Name Type Format Description
BillToAddress object BillToAddress The billing address associated with the invoice.
CalculatedTaxAmount string - The calculated tax amount for the invoice.
CalculatedTaxRate string - The calculated tax rate for the invoice.
Comments string - Comments for the invoice.
CountryCode string - The country code for the line item.
CurrencyCode string - The 3-letter ISO 4217 currency code for the invoice currency. Example: USD, CAD
ID string - The unique identifier of the resource.
InvoiceAmount string - The invoice amount (the cost of the purchased items).
InvoiceDate string - The date of the invoice.
LineItem array LineItem The line items associated with the invoice.
OrgUnit1 through OrgUnit6 string - Not available for PUT. The code from the OrgUnit fields. These fields may not have data, depending on the configuration.
OrgUnit1Value though OrgUnit6Value string - Not available for PUT. The value from the OrgUnit fields. These fields may not have data, depending on the configuration.
Custom1 through Custom24 string - Not available for PUT. The code from the Custom fields. These fields may not have data, depending on the configuration.
Custom1Value through Custom24Value string - Not available for PUT. The value from the Custom fields. These fields may not have data, depending on the configuration.
PurchaseOrderNumber string - The purchase order number associated to the invoice.
RequestID string - The ID of the invoice.
ShippingAmount string - The shipping amount for the invoice.
ShipToAddress object ShipToAddress The shipping address associated with the invoice.
Status string - The status of the invoice.
StatusCode string - Required The status code for the invoice. Supported values: ERROR, CMPLT
Tax string - The tax, as shown on the invoice. This is the tax applied by the vendor.
TaxReferenceID string - Required The tax reference ID of the invoice.
Title string - The title of the invoice.
Total string - The total amount of the invoice.
URI string - The URI to the resource.
VendorInvoiceNumber string - The vendor invoice number that is associated with the invoice.

BillToAddress

Name Type Format Description
Address1 string - Required Address line 1 of the billing address.
Address2 string - Address line 2 of the billing address.
Address3 string - Address line 3 of the billing address.
City string - Required The city of the billing address.
CountryCode string - Required The code of the country for the billing address.
ExternalID string - Required A unique value supplied by the customer to identify a particular billing address.
Name string - An optional name that can be given to the billing address.
PostalCode string - Required The postal code of the billing address.
State string - Required The state of the billing address.
StateProvince string - Required The province of the billing address.

LineItem

Name Type Format Description
Allocations object Allocation The allocations associated with a line item.
CalculatedTaxAmount string - The calculated tax amount for the individual line item.
CalculatedTaxRate string - The calculated tax rate for the individual line item.
CommodityCode string - The commodity code that is tied to the expense type associated with the line item.
CountryCode string - The country code for the line item.
CurrencyCode string - The currency code for the individual line item.
LineItemKey string - Required A value that uniquely identifies the line item.
Quantity string - The quantity for the line item.
Total string - The total amount for the line item.
UnitPrice string - The unit price for the line item.
Vendor object InvoiceVendor Details about the vendor for each line item.

Allocation

Name Type Format Description
AllocationAmount string - The allocation amount associated with the line item.
Custom1 through Custom20 string - Not available for PUT. The code from the Custom fields. These fields may not have data, depending on the configuration.
Custom1Value through Custom20Value string - Not available for PUT. The value from the Custom fields. These fields may not have data, depending on the configuration.

Vendor

Name Type Format Description
Address1 string - Required Address line 1 of the vendor address.
Address2 string - Address line 2 of the vendor address.
Address3 string - Address line 3 of the vendor address.
City string - Required The city of the vendor address.
CountryCode string - Required The code of the country for the vendor address.
PostalCode string - Required The postal code of the vendor address.
State string - Required The state of the vendor address.
VendorAddressName string - Required The name for the vendor address.
VendorName string - Required The name of the vendor.
VendorCode string - Required The code associated with the vendor.

ShipToAddress

Name Type Format Description
Address1 string - Required Address line 1 of the shipping address.
Address2 string - Address line 2 of the shipping address.
Address3 string - Address line 3 of the shipping address.
City string - Required The city of the shipping address.
CountryCode string - Required The code of the country for the shipping address.
ExternalID string - Required A unique value supplied by the customer to identify a particular shipping address.
Name string - An optional name that can be given to the shipping address.
PostalCode string - Required The postal code of the shipping address.
State string - Required The state of the shipping address.
StateProvince string - Required The province of the shipping address.

Status Schema

Name Type Format Description
Code int - Code of request result.
Comments string - Comments that are returned for the update request.
Message string - Message of request result.
RecordNumber int - Record number for the create/update request.
Status string - The status of the update. Supported values: SUCCESS, FAILURE
TaxReferenceID string - The tax reference ID of the updated invoice.
Type string - Type request result.

Vendor v3

The Vendor API allows you to develop processes that can be used to manage your Vendor collection for invoicing, adding new Vendors, updating, getting, or deleting information for existing Vendors.

Limitations: This API is only available to partners who have been granted access by SAP Concur. Access to this documentation does not provide access to the API. This API is not available in the China data center.

Products and Editions

Scope Usage

Name Description Endpoint
INVVEN Retrieves vendor information. GET

Dependencies

SAP Concur clients must purchase Concur Invoice in order to use this API.

Access Token Usage

This API supports both company level and user level access tokens.

Retrieve an Existing Vendor

Note: If authenticating with a Company access token the API will return all vendors associated with a specific entity.

GET /api/v3.0/invoice/vendors

Parameters

Name Type Format Description
limit Int32 query The maximum number of items to be returned in a response. The default is 25 and cannot exceed 1000.
offset string query Specifies the starting point for the next query when iterating through the collection response. Use with paged collections of resources.
sortDirection string query Ascending or descending, The default value will be ascending.
sortBy string query Field you need the results to be sorted by. Vendor Name will be made default if no value is sent. Only fields that are added to the vendor form can be used here. Fields have to be specified by name as specified in Doc.
searchType string query Applies for the entire given search parameters. The default value is exact. Supported values: exact, begins, contains, ends
vendorCode string query Vendor Code to be searched
vendorName string query Vendor Name to be searched
taxID string query Tax ID to be searched
buyerAccountNumber string query Buyer Account Number to be searched
paymentMethodType string query Payment Method Type - valid values are ACH, CARD, CHECK, CLIENT, PAYPVD, VCHER, WIRE
addressCode string query Address Code to be searched
address1 string query Address 1 to be searched
address2 string query Address 2 to be searched
address3 string query Address 3 to be searched
city string query City to be searched
state string query State to be searched
postalCode string query Postal Code to be searched
approved string query Find Approved/Unapproved Vendors, True/False
country string query Country to be searched
custom1 string query Custom 1 to be searched
custom2 string query Custom 2 to be searched
custom3 string query Custom 3 to be searched
custom4 string query Custom 4 to be searched
custom5 string query Custom 5 to be searched
custom6 string query Custom 6 to be searched
custom7 string query Custom 7 to be searched
custom8 string query Custom 8 to be searched
custom9 string query Custom 9 to be searched
custom10 string query Custom 10 to be searched
custom11 string query Custom 11 to be searched
custom12 string query Custom 12 to be searched
custom13 string query Custom 13 to be searched
custom14 string query Custom 14 to be searched
custom15 string query Custom 15 to be searched
custom16 string query Custom 16 to be searched
custom17 string query Custom 17 to be searched
custom18 string query Custom 18 to be searched
custom19 string query Custom 19 to be searched
custom20 string query Custom 20 to be searched

Input

None.

Response

Vendors Schema

Create Vendors

POST /api/v3.0/invoice/vendors Note: If authenticating with a Company access token, the API will create the requested Vendors.

Parameters

Name Type Format Description
vendors - body The vendor details.

Input

Vendors Schema

Response

Vendors Schema

Update Existing Vendors

PUT /api/v3.0/invoice/vendors Note: If authenticating with a Company access token, the API will update the requested Vendors.

Parameters

Name Type Format Description
vendors - body The vendor details.

Input

Vendors Schema

Response

Vendors Schema

Delete Vendor

DELETE /api/v3.0/invoice/vendors Note: If authenticating with a Company access token, the API will delete the requested Vendor.

Parameters

Name Type Format Description
vendorCode string query Required Vendor Code to be deleted
addressCode string query Required Address Code to be deleted

Input

None.

Response

Vendors Schema

Add/Update Vendor Banking

PUT /api/v3.0/invoice/vendor/banks Note: If authenticating with a Company access token, the API will create / update the requested Vendor Banking info.

Parameters

Name Type Format Description
vendorBanks - body The vendor banking info

Input

Vendor Bank Schema

Response

Vendor Bank Schema

Add Vendor Group

PUT /api/v3.0/invoice/vendor/groups Note: If authenticating with a Company access token, the API will create the requested Vendor groups.

Parameters

Name Type Format Description
vendorCode string query Required The vendor code of the vendor to update
addressCode string query Requred The address code of the vendor to update
vendorGroups - body The vendor group details

Input

Vendor Group Schema

Response

Vendor Group Schema

Delete Vendor Group

DELETE /api/v3.0/invoice/vendor/groups Note: If authenticating with a Company access token, the API will delete the requested Vendor group.

Parameters

Name Type Format Description
vendorCode string query Required The vendor code of the vendor to update
addressCode string query Requred The address code of the vendor to update
groupName string query Requred The group name to be deleted

Input

None.

Response

Vendor Group Schema

Schema

Vendors

Name Type Format Description
Items array Vendor The result collection.
NextPage string - The URI of the next page of results, if any.
RequestRunSummary string - -
TotalCount Int - -
Vendor array Vendor Required Vendor

Vendor

Name Type Format Description
AccountNumber string - The Buyer Account Number.
Address1 string - The Vendor Address 1.
Address2 string - The Vendor Address 2.
Address3 string - The Vendor Address 3.
AddressCode string - Required The Address Code.
AddressImportSyncID string - This ID is originally generated by Invoice when an employee requests a new vendor. The Employee Request Vendor Extract provides this value to positively identify the vendor address record when reimporting vendor from the client's system of record for the Vendor Master List.
Approved string - Vendor Approval Status.
City string - The Vendor City.
ContactEmail string - The Vendor Contact Email.
ContactFirstName string - The Vendor Contact First Name.
ContactLastName string - The Vendor Contact Last Name.
ContactPhoneNumber string - The Vendor Contact Phone Number.
Country string - The Vendor Country.
CountryCode string - The Vendor Country Code.
CurrencyCode string - The Vendor Currency Code.
Custom1 string - A value that can be applied to a custom field 1 that is part of the vendor form.
Custom10 string - A value that can be applied to a custom field 10 that is part of the vendor form.
Custom11 string - A value that can be applied to a custom field 11 that is part of the vendor form.
Custom12 string - A value that can be applied to a custom field 12 that is part of the vendor form.
Custom13 string - A value that can be applied to a custom field 13 that is part of the vendor form.
Custom14 string - A value that can be applied to a custom field 14 that is part of the vendor form.
Custom15 string - A value that can be applied to a custom field 15 that is part of the vendor form.
Custom16 string - A value that can be applied to a custom field 16 that is part of the vendor form.
Custom17 string - A value that can be applied to a custom field 17 that is part of the vendor form.
Custom18 string - A value that can be applied to a custom field 18 that is part of the vendor form.
Custom19 string - A value that can be applied to a custom field 19 that is part of the vendor form.
Custom2 string - A value that can be applied to a custom field 2 that is part of the vendor form.
Custom20 string - A value that can be applied to a custom field 20 that is part of the vendor form.
Custom3 string - A value that can be applied to a custom field 3 that is part of the vendor form.
Custom4 string - A value that can be applied to a custom field 4 that is part of the vendor form.
Custom5 string - A value that can be applied to a custom field 5 that is part of the vendor form.
Custom6 string - A value that can be applied to a custom field 6 that is part of the vendor form.
Custom7 string - A value that can be applied to a custom field 7 that is part of the vendor form.
Custom8 string - A value that can be applied to a custom field 8 that is part of the vendor form.
Custom9 string - A value that can be applied to a custom field 9 that is part of the vendor form.
DefaultEmployeeID string - The Default Employee ID of the employee connected to the vendor.
DefaultExpenseTypeName string - The Default Expense Type tied to the vendor.
DiscountPercentage string - The Discount Percentage.
DiscountTermsDays string - The Vendor Discount Terms Days.
ID string - The unique identifier of the resource.
IsLineItemVatIncld string - Line item Unit Price Contains VAT ,
IsVisibleForContentExtraction string - Flag that indicates if the vendor will be available for OCR within Brainware
PaymentMethodType string - Preferred Payment Type for Vendor.
PaymentTerms Integer between 1 and 999 - The Vendor Payment Terms. This field represents the number of days by which a payment must be made, for example, 30 days
PostalCode string - The Vendor Postal Code / Zip.
ProvincialTaxID string - The Vendor Provincial Tax ID. Note that this value is not encrypted at REST.
PurchaseOrderContactEmail string - The Purchase Order Contact Email.
PurchaseOrderContactFirstName string - The Purchase Order Contact First Name.
PurchaseOrderContactLastName string - The Purchase Order Contact Last Name.
PurchaseOrderContactPhoneNumber string - The Purchase Order Contact Phone Number.
ShippingMethod string - The Vendor Shipping Method.
ShippingTerms string - The Vendor Shipping Terms.
State string - The Vendor State.
StatusList array Status Required Status results
TaxID string - The Vendor Tax ID. Note that this value is not encrypted at REST.
TaxType string - The Vendor Tax Type.
URI string - The URI to the resource.
VendorBankList array VendorBank The list of a vendor's active banking information. Read-Only
VendorCode string - Required The vendor code of the request.
VendorFormName string - The vendor form name this vendor is associated with.
VendorGroupList array - The list of vendor groups by name. Read-Only
VendorName string - The name of the vendor.
VoucherNotes string - Notes sent to Vendor along with authorization to charge Card Voucher.

Vendor Banking Input/Response Schema

Name Type Format Description
Items array VendorBank The result collection.
NextPage string - The URI of the next page of results, if any.
RequestRunSummary string - -
TotalCount Int - -
VendorBank array VendorBank Required Vendor Banking Info

VendorBank

Name Type Format Description
AccountNumber string - Required The account number.
AccountType enum - Required The account type--CHCK for Checking, SAVE for Savings.
AddressCode string - Required The Address Code.
BankCode string - Bank Code
BankName string - The bank name.
BranchCode string - Branch Code
BranchLocation string - The branch location
CountryCode string - The country code.
CurrencyAlphaCode string - The currency alpha Code.
ID string - The unique idenitifier of this resource.
IsActive string - Required Is information active
NameOnAccount string - Required The name on the account.
RoutingNumber string - The routing number.
StatusList array status Status results
TransType string - The trans type.
URI string - The URI to the resource.
VendorCode string - Required The vendor code of the request.

Vendor Group Input/Response Schema

Name Type Format Description
Items array VendorGroup The result collection.
NextPage string - The URI of the next page of results, if any.
RequestRunSummary string - -
TotalCount Int - -
VendorGroup array VendorGroup Required Vendor Group List

VendorGroup

Name Type Format Description
ID string - The unique identifier of the resource.
Name string - Required The vendor group name.
StatusList array status Status results.
URI string - The URI to the resource.

Status

Name Type Format Description
Code int - Code of request result
Message string - Message of request result
RecordNumber int - Record Number for create/update request.
Type string - Type request result

Invoice Pay v4

Overview

SAP Concur partners with external payment providers for processing invoice payments. These payment providers are listed on the App Center and can integrate with the Invoice product by using the Invoice Pay APIs. Payment providers can get a list of all the payments authorized to be processed by them, and send back status of those payments.

Limitations: This API is only available for use by payment partners who will be processing invoice payments. This API can accept a maximum of 10,000 requests per minute across all payment providers. This API is available only in the North America Data Center.

Process Flow

A process flow diagram of the Invoice Pay API

Products and Editions

Scope Usage

Name Description Endpoint
invoice.providerpayment.write Read access to pending payments, and write access to payment status GET,POST

Dependencies

This API can only be used with SAP Concur clients who have purchased Concur Invoice.

Access Token Usage

This API supports only Company access tokens.

Obtaining payments

Payment providers can use this endpoint to get a list of payments. * This method will return all payments with a status PENDING_RETRIEVAL and payment method PAVPVD. After an invoice is approved and extracted it will be converted into a payment with status PENDING_RETRIEVAL. * It returns a maximum of 500 records at a time. In order to ensure that all payments are retrieved, call this method until you receive an empty payment in the response. * The payment provider will need to acknowledge that payments were received, using Updating a Payment With Status and updating the status of the payment to any status other than PENDING_RETRIEVAL.

Request

URI

Template
GET https://us.api.concursolutions.com/invoice/provider-payment/v4/payments
Parameters
Name Type Format Description
invoiceId string - Optional: Gets specific payment info along with erpDocumentNumber.

Headers

Payload

None.

Response

Status Codes

Headers

Payload

Payments

Example

Request

GET https://us.api.concursolutions.com/invoice/provider-payment/v4/payments
Accept: application/json
Authorization: BEARER {token}

Response

200 OK
Content-Type: application/json
{
  "payments": [
    {
      "paymentId": "0f27533f-ce38-4f43-a2f3-fa9f0e6b33fc",
      "paymentMethod": "PAYPVD",
      "paymentDueDate": "2018-08-09",
      "totalAmount":{
        "amount": "30.00",
        "currency": "USD"
      },
      "invoices": [
        {
          "invoiceNumber": "AGH87",
          "invoiceID": "1ADFBB440D7045F68DE2",
          "invoiceAmount":{
            "amount": "30.00",
            "currency": "USD"
          },
          "paymentAmount":{
            "amount": "30.00",
            "currency": "USD"
          },
          "notesToSupplier": null,
          "erpDocumentNumber": "erp1234"
        }
      ],
      "vendor":{
        "addressLine1": "1234 Rain Street",
        "addressLine2": null,
        "addressLine3": null,
        "vendorAddrCode": "1160",
        "city": "Chicago",
        "state": "IL",
        "postalCode": "60680-28160",
        "countryName": "UNITED STATES",
        "countryCode": "US",
        "firstName": "Terry",
        "lastName": "Brown",
        "phoneNumber": null,
        "email": "terry.brown@example.com",
        "vendorCode": "1160",
        "vendorName": "Dell",
        "buyerAccountNumber": "1234567890"
      }
    }
  ]
}

Updating a Payment With Status

Payment providers can use this endpoint to provide updates to the status of payments.

Request

URI

Template
POST https://us.api.concursolutions.com/invoice/provider-payment/v4/payments/{paymentId}

Parameters

Name Type Format Description
paymentId string - Required The identifier of the payment to update.

Headers

Payload

Payment Update

Response

Status Codes

Headers

Payload

Payment Update Result

Example

Request

POST https://us.api.concursolutions.com/invoice/provider-payment/v4/payments/0f27533f-ce38-4f43-a2f3-fa9f0e6b33fc
Authorization: BEARER {token}
Content-Type: application/json
{
  "providerReference" : "hdoesofdl",
  "status" : "PAID",
  "statusMessage" : "Payment was successful",
  "paymentAdjustmentNotes" : null,
  "statusDate" : "2018-05-10",
  "paymentInitiationDate" : "2018-05-09",
  "paymentSettlementDate" : "2018-05-09",
  "thirdPartyPaymentIdentifier" : "69249",
  "paymentMethod" : "CHECK",
  "paidAmount" : {
    "amount": "30.00",
    "currency": "USD"
  }
}

Response

200 OK
Content-Type: application/json
{
  "createdDate" : "2018-05-09",
  "lastModifiedDate" : "2018-05-09",
  "status" : "PAID",
  "statusMessage" : "Payment was successful",
  "paymentAdjustmentNotes" : null,
  "statusDate" : "2018-05-10",
  "paymentInitiationDate" : "2018-05-09",
  "paymentSettlementDate" : "2018-05-09",
  "thirdPartyPaymentIdentifier" : "69249",
  "paymentMethod" : "CHECK",
  "paidAmount" : {
    "amount": "30.00",
    "currency": "USD"
  }
}

Schema

Payments

Name Type Format Description
payments array Payment Array of payments.

Payment

Name Type Format Description
invoices array Invoice Array of invoices that need to be batched in a payment.
paymentDueDate string YYYY-MM-DD The date by which the payment should be made.
paymentID string - Unique identifier of the payment in SAP Concur. Maximum 36 characters.
paymentMethod string - The value is always PAYPVD which means that the client wants to pay using a payment provider. Maximum 15 characters.
totalAmount object Amount This amount needs to be paid to the vendor.
vendor object Vendor Vendor requesting the payment.

Invoice

Name Type Format Description
invoiceAmount object Amount Amount on the invoice.
invoiceNumber string - Invoice Number. Maximum 50 characters.
invoiceId string - Unique identifier of the invoice in SAP Concur. This can be used to get additional invoice information from other APIs. This is the same as paymentRequestID in other Invoice APIs. Maximum 20 characters.
notesToSupplier string - Notes to the supplier contain remittance information that the buyer wants to provide to the supplier. Maximum 500 characters.
paymentAmount object Amount Payment amount on the invoice.
erpDocumentNumber string - ErpDocumentNumber of that invoice.

Vendor

Name Type Format Description
buyerAccountNumber string - Buyer Account Number. Maximum 50 characters.
vendorCode string - Vendor Code. Maximum 32 characters.
vendorName string - Vendor Name. Maximum 255 characters.
addressLine1 string - Vendor Address line 1. Maximum 255 characters.
addressLine2 string - Vendor Address line 2. Maximum 255 characters.
addressLine3 string - Vendor Address line 3. Maximum 255 characters.
city string - Vendor Address City. Maximum 255 characters.
state string - Vendor Address State. Maximum 10 characters.
countryCode string - Vendor Address Country Code. Maximum 2 characters.
countryName string - Vendor Address Country Name. Maximum 64 characters.
postalCode string - Vendor Address Postal Code. Maximum 20 characters.
vendorAddrCode string - Vendor Address Code. Maximum 64 characters.
email string - Email Address. Maximum 255 characters.
firstName string - First Name. Maximum 255 characters.
lastName string - Last Name. Maximum 255 characters.
phoneNumber string - Phone Number. Maximum 25 characters.

Amount

Name Type Format Description
amount string - Amount. Maximum 20 characters.
currency string - Currency Code. Maximum 3 characters.

Payment Update

Name Type Format Description
providerReference string - Unique identifier of the payment in the payment provider's system. This will be used for internal troubleshooting. Maximum 100 characters.
status string Payment Update Status Required Used to depict success, error or any other intermediate state, defined by SAP Concur.
statusMessage string - Payment provider description of the status. Providers can supply any message. Maximum 255 characters.
paymentAdjustmentNotes string - Payment adjustment notes sent by the payment provider. Maximum 255 characters.
statusDate string YYYY-MM-DD Required The date that the payment provider recorded this status change.
paymentInitiationDate string YYYY-MM-DD The date the payment was initiated.
paymentSettlementDate string YYYY-MM-DD The date the payment will be in the payees account.
thirdPartyPaymentIdentifier string - Check number if the payment was done via check or trace number for ACH payments. Maximum 255 characters.
paymentMethod string Payment Provider Method Required if the status is PAID, CHECK_PROCESSED, or CARD_SETTLED Payment method used by the payment provider.
paidAmount object Amount Required if the status is PAID, CHECK_PROCESSED, or CARD_SETTLED Amount paid by the payment provider.

Payment Update Result

Name Type Format Description
createdDate string YYYY-MM-DD The date the payment was created.
lastModifiedDate string YYYY-MM-DD The date the payment was last modified.
providerReference string - Unique identifier of the payment in the payment provider's system. Maximum 100 characters.
status string Payment Update Status Required Used to depict success, error or any other intermediate state, defined by SAP Concur.
statusMessage string - Payment provider description of the status. Providers can supply any message. Maximum 255 characters.
paymentAdjustmentNotes string - Payment adjustment notes sent by the payment provider. Maximum 255 characters.
statusDate string YYYY-MM-DD Required The date that the payment provider recorded this status change.
paymentInitiationDate string YYYY-MM-DD The date the payment was initiated.
paymentSettlementDate string YYYY-MM-DD The date the payment will be in the payees account.
thirdPartyPaymentIdentifier string - Check number if the payment was done via check or trace number for ACH payments. Maximum 255 characters.
paymentMethod string Payment Provider Method Required if the status is PAID, CHECK_PROCESSED, or CARD_SETTLED Payment method used by the payment provider.
paidAmount object Amount Required if the status is PAID, CHECK_PROCESSED, or CARD_SETTLED Amount paid by the payment provider.

Errors

Name Type Format Description
errors array Error An array of errors.

Error

Name Type Format Description
errorCode string - Required Machine readable code associated with the error.
errorMessage string - Required Human readable message associated with the error.

Definitions

Payment Update Status

Value Description Status available in the Payment Confirmation Extract
PENDING_RETRIEVAL Not yet retrieved by the payment provider Not available
RETRIEVED Retrieved by the payment provider Not available
PROCESSING Payment is being processed by the payment provider Not available
REJECTED Payment was rejected by the payment provider Not available
RETURNED Payment was returned by the bank Not available
CANCELED Payment was canceled FAILED
CHECK_PRINTED Check was printed Not available
CHECK_MAILED Check was mailed Not available
CHECK_PROCESSED Check was processed PAID
CHECK_VOIDED Check was voided VOID
PAID Payment was successfully made PAID
CARD_EMAIL_SENT Email with card information sent to vendor Not available
CARD_AUTHORIZED Card was authorized by the merchant Not available
CARD_SETTLED Card was settled by vendor PAID

Payment Provider Method

Value Description
ACH ACH payment
CHECK Check payment
WIRE Wire payment
CARD Virtual Card payment
OTHER Any other payment method

Purchase Request v4 - Endpoints

Version

4.0

Create a New Purchase Request

Create a Purchase Request based on provided header and line item details. If the request is valid it creates a purchase request and returns back a unique identifier to get the purchase request details.

Scopes

purchaserequest.write - Refer to Scope Usage for full details.

Request

URI

Template
POST /purchaserequest/v4/purchaserequests
Parameters

None

Headers

Payload

Response

Status Codes

Headers

Payload

Example

Request

This is a sample set of fields. The fields and values your entity requires will vary based on your edition of Concur Invoice, and your forms and fields configuration. This example includes commonly used fields.

POST /purchaserequest/v4/purchaserequests
Authorization: Bearer {token}
Content-Type: application/json
{
  "description" : "New office supplies",
  "userLoginId" : "john.deo@concur",
  "policyExternalId" : "po-external-id",
  "currencyCode" : "USD",
  "notesToSupplier" : "Office space request phase 1",
  "comments" : "office supplies request",
  "custom1" : "ADVT",
  "shipToAddressCode" : "SHIP15139",
  "billToAddressCode" : "MNSLP129",
  "lineItems" : [
    {
      "purchaseType" : "SERVICES",
      "vendorCode" :"VEN1",
      "vendorAddressCode" : "ADDR1",
      "description" : "monitor",
      "quantity" : "20",
      "unitPrice" : "154.4",
      "expenseType" : "1250",
      "receiptType" : "NONE",
      "neededByDate": "2018-06-28",
      "uomCode" : "DA",
      "shipping" : "13.5",
      "tax" : "11",
      "supplierPartId" : "DAQT1",
      "url" :[
        "http://officesupplies.com/monitor"
      ],
      "notesToVendor" : "Phase 1 request monitor",
      "comments" : "Phase 1 request for new employees for monitor",
      "custom2" : "LGVT1"
    },
    {
      "purchaseType" : "GOODS",
      "vendorCode" :"VEN1",
      "vendorAddressCode" : "ADDR1",
      "description" : "office chair",
      "quantity" : "20",
      "unitPrice" : "346.2",
      "expenseType" : "1251",
      "receiptType" : "QUANTITY_RECEIPT",
      "neededByDate": "2018-06-28",
      "uomCode" : "DA",
      "shipping" : "15",
      "tax" : "17.5",
      "supplierPartId" : "DAQT2",
      "url" :[
        "http://officesupplies.com/officechair"
      ],
      "notesToVendor" : "Phase 1 request office chair",
      "comments" : "Phase 1 request for new employees for office chair",
      "custom3" : "DEPT",
      "custom4" : "SALES"
    }
  ]
}

Response

HTTP/1.1 202 Accepted
Content-Type: application/json
Date: date-requested
Content-Length: 1000
concur-correlationid: 1234abcd-12ab-34cd-56ef-123456abcdef
{
  "id" : "b1e22581-ff4a-48e9-981b-2f5065579096",
  "uri": "http://us.api.concursolutions.com/purchaserequest/v4/purchaserequests/b1e22581-ff4a-48e9-981b-2f5065579096?mode=COMPACT"
}

Get Purchase Request Details

Gets purchase request details. The supported mode is COMPACT, which returns basic info about the purchase request along with any exceptions.

Scopes

purchaserequest.read - Refer to Scope Usage for full details.

Request

URI

Template
GET /purchaserequest/v4/purchaserequests/{id}?mode=COMPACT
Parameters
Name Type Format Description
mode string - Required: Specifies mode for Get Purchase Request Details. Supported value: COMPACT

Headers

Payload

None

Response

Status Codes

Headers

Payload

Example

Request

GET /purchaserequest/v4/purchaserequests/de9c0894-b807-6943-8e3f-49a707da3456?mode=COMPACT
Authorization: Bearer {token}
Content-Type: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json
Date: date-requested
Content-Length: 1000
concur-correlationid: 1234abcd-12ab-34cd-56ef-123456abcdef
{
  "purchaseRequestId" : "de9c0894-b807-6943-8e3f-49a707da3456",
  "purchaseRequestNumber" : "100000",
  "purchaseRequestQueueStatus" : "CREATED",
  "purchaseRequestWorkflowStatus" : "Approved",
  "purchaseRequestExceptions": [
    {
      "message": "Line Item Quantity does not match",
      "eventCode": "PURCH_DETAIL_ITEM_SAVE",
      "exceptionCode": "0070071",
      "isCleared": false,
      "prExceptionId": "fe636831-43a1-9540-bf86-32e2c19400af"
    }
  ],
  "purchaseOrders": [
    {
      "purchaseOrderNumber": "PO10001"
    }
  ]        
}

Schema

Create Purchase Request Schema

Name Type Format Description
userId string - Required: The employee that is requesting the items. This is the UUID of the employee. Either UserId or UserEmail or UserLoginId is required to identify the employee.
userEmail string - Required: The employee that is requesting the items. This is the employee's email. Either UserId or UserEmail or UserLoginId is required to identify the employee.
userLoginId string - Required: The employee that is requesting the items. This is the employee's Login Id. Either UserId or UserEmail or UserLoginId is required to identify the employee.
description string - A description of the purchase request.
policyExternalId string - The external identifier of the policy that should be associated with the purchase request. If not supplied, the API will use the default policy set up for the user group assigned to the requesting employee. This is the External Id from the Invoice Policy configuration. Clients will need to get these Ids from their SAP Concur contact if they need to assign policies other than the group default.
currencyCode string - Required: The 3-letter ISO 4217 currency code of the currency that is associated with the purchase request. This code will be used for all items on this request. Example: USD
notesToSupplier string - Notes to print on the transmitted purchase order PDF sent to the supplier.
comments string - Internal comments related to this record.
custom1 through custom24 string - Each custom field used should have its own row in the message. If the field is tied to a connected list, the accepted value is the list Item Code configured for the list in SAP Concur.
shipToAddressCode string - The shipping address of the Purchase Request. The accepted value is the address code from ShipTo record. If not supplied, the API will use the requesting user's default shipping address.
billToAddressCode string - The billing address of the Purchase Request to be used for invoicing. The accepted value is the address code from the BillTo record. If not supplied the API will use the policy's default BillTo address.
lineItems array LineItem Required: Requested items or services related to this Purchase Request.

LineItem

Name Type Format Description
purchaseType string - Required: The type of item, either goods or services. Displayed as Type in Concur Invoice. Supported values: GOODS, SERVICES.
vendorCode string - Required: The code that identifies the vendor. This value can be found in the vendor information form of Vendor Manager. This is used along with Vendor Address Code to determine the specific Vendor record.
vendorAddressCode string - Required: The code that identifies the vendor's address. This value can be found in the vendor information form of Vendor Manager and is labeled Address Accounting Code. This is used along with Vendor Code to determine the specific Vendor record.
description string - Required: A description of the line item.
quantity decimal - Required: The quantity associated with the line item.
unitPrice decimal - Required: The unit price of the line item.
expenseType string - The PET code of the Expense Type that will be assigned to the line item. If not supplied it will default to the Expense Type set up on the Vendor Profile used for the item. Clients will need to get these PET codes from their SAP Concur contact.
receiptType string - The type of receipt. If not supplied, the API will use the purchaseType to set this field to NONE for SERVICES, or QUANTITY_RECEIPT for GOODS. If you are using SAP Concur Receiving and need to enter Goods Receipts against the resulting PO lines use QUANTITY_RECEIPT. Supported values: QUANTITY_RECEIPT, NONE.
neededByDate date YYYY-MM-DD The date by which the purchase order must be fulfilled. Example: 2018-03-23
uoMCode string - Unit of Measure (UOM) code for the purchase request item. Accepted values are the UOM Codes set up in the Unit of Measure configuration in Concur Invoice. If not supplied, the API will default a UOM based on the defaults for goods and services.
shipping decimal - The total shipping cost for the item.
tax decimal - Tax amount that is associated with the line item.
supplierPartId string - An Id value that helps to identify the line item. This could be a value such as the vendor’s part number or the manufacturer number.
url array - A URL related to the item. You can have multiple URLs per item, enclosed in quotes and comma separated.
notesToVendor string - Notes related to the item that display on the transmitted purchase order PDF to the vendor.
comments string - Internal comments related to this record.
custom1 through custom20 string - Each custom field used should have its own row in the message. If the field is tied to a connected list, the accepted value is the List Item Code configured for the list in SAP Concur.

Create Purchase Request Response Schema

Name Type Format Description
errors array Error An array of errors indicating which fields have failed validation.
id string - The unique purchase request reference ID if the request has passed all validations. This reference ID will be needed to look up details of the purchase request.
uri string - The URI to look up details of the newly created purchase request.

Get Purchase Request Response Schema

Name Type Format Description
purchaseRequestId string - The unique purchase request reference Id. Returned by the Create Purchase Request API call.
purchaseRequestNumber string - The unique purchase request identifier which can be used to uniquely identify a purchase request in SAP Concur products.
purchaseRequestQueueStatus string - The creation status of the purchase request. Possible values are: PENDING_CREATION, CREATED, CREATE_FAILED.
purchaseRequestWorkflowStatus string - The workflow status of the purchase request. Possible values are: Approved, Pending Approval, Pending Cost Object Approval, Sent Back To Employee, Not Submitted, Submitted, Pending Processor Review, Vendor Approval, Approval Time Expired.
purchaseOrders array PurchaseOrders If the purchase request has been approved and a purchase order generated, this array contains the purchase order details. If empty, this element will not be returned.
purchaseRequestExceptions array PurchaseRequestExceptions An array of exceptions, if present on the purchase request. If empty, this element will not be returned.

PurchaseOrders

Name Type Format Description
purchaseOrderNumber string - The purchase order number.

PurchaseRequestExceptions

Name Type Format Description
eventCode string - The event code of the exception. Example: PURCH_DETAIL_SUBMIT
exceptionCode string - The unique exception code.
isCleared boolean - Whether the exception has been cleared.
prExceptionId string - The unique exception id of the purchase request.
message string - The message of the exception with details.

Error

Name Type Format Description
errorCode string - An error code indicating why a field failed validation.
errorMessage string - A description of the error.
dataPath string - The path to the request data which has the error message.

Error Codes When the HTTP Status Code is 4xx

ErrorCode Error Message
missingRequestBody Missing request body.
invalidRequestBody Passed request body is invalid.
missingUserInfo Either userID or userEmail or userLoginId is required.
invalidUserInfo Either userID or userEmail or userLoginId is invalid, or user does not have access to this resource.
provideOneUserInformation Either userID or userEmail or userLoginId is required.
missingCurrencyCode currencyCode is missing.
invalidCurrencyCode currencyCode is invalid.
invalidPolicyInformation Cannot find a purchase order policy with the supplied policyExternalId.
missingLineItems lineItems are missing.
invalidPurchaseType purchaseType is invalid.
missingPurchaseType purchaseType is required.
missingVendorAddressCode vendorAddressCode is required.
missingVendorCode vendorCode is required.
invalidVendor Vendor / Address code combination is invalid.
missingDescription Line item description is required.
missingQuantity Line item quantity is required.
invalidQuantity Line item quantity is invalid.
missingUnitPrice unitPrice is required.
invalidUnitPrice unitPrice is invalid.
invalidDateFormat Expected a date in the format YYYY-MM-DD.

Purchase Request v4 - Get Started

The Purchase Request API gives SAP Concur clients the ability to leverage external data to create purchase requests for pre-authorization of purchase orders. Clients can build a direct connection to the Purchase Request API which will create new purchase requests and automatically submit them into the pre-authorization workflow. Once approved, the purchase request results in a purchase order that can be transmitted to a vendor from SAP Concur.

Use Case

Many Concur Invoice clients have external systems that have part or service lists with pricing. If they use SAP Concur pre-authorization using purchase request, the data from the external systems must be entered manually into the purchase request cart and submitted for approval by the requesting employee. Using this API and a client-built integration, the requestor can browse and select the items from the external system with quantities and other details needed, and then send the data to SAP Concur. A purchase request will be created and submitted into the workflow. The API returns a response message with a record identifier (URI), which can be used with the Get Purchase Request Details method to get the basic details of the created purchase request: Concur Purchase Request number, workflow status, exceptions, and once approved, the resulting SAP Concur purchase order number.

Limitations

This API is not available in the China Data center. This API is only available for direct integrations with an existing SAP Concur client. If you are a Partner looking to build an App Center App using this API, please reach out to your SAP Concur Representative. This API can only be used to create new purchase requests and get the details of the created purchase request. This API cannot update, edit, or delete purchase requests. All edits or processing of the purchase request after it is sent to SAP Concur and created must be done in SAP Concur.

Regional Availability

https://us.api.concursolutions.com/purchaserequest/v4/
https://emea.api.concursolutions.com/purchaserequest/v4/

Products and Editions

Scope Usage

Name Description Endpoint
purchaserequest.write Allows you to create new purchase requests POST
purchaserequest.read Allows you to retrieve purchase requests GET

Dependencies

SAP Concur clients must purchase Concur Invoice, Concur Purchasing, and Concur Web Services in order to use this API. Concur Invoice with Concur Purchasing must be configured before using this API.

To create purchase requests, you need to supply a Vendor Code and Vendor Address Code. You can access Vendor Manager in Concur Invoice to see these values. If you need to get this data from SAP Concur using web services, you can use the Vendor v3 API.

If your purchase request form in SAP Concur has required custom fields that are tied to lists, you will need to supply the Item Code for the list items, or configure them to copy down from another source such as Employee. You can access List Management in SAP Concur to see your list items and list item codes. If you need to get this data from SAP Concur using web services, you can use the List Item v3 API to retrieve the Level1Code value for the list items.

Access Token Usage

This API will work with both Company or User access tokens, however a Company access token is required if the integration will create purchase requests for multiple requestors. Using a User access token to create purchase requests results in the purchase request being assigned to the user that generated the User access token, not the user set in the payload. A User access token can be used for testing purposes.

Retrieve a Company Access Token

Clients connecting to this API to build a custom integration will receive client credentials and information on how to generate your Company access token or Company refresh token from your Concur Technical Enablement resource.

Retrieve a User Access Token

This API supports User access tokens, however any purchase requests created using a User access token will only create/assign these requests to the user that generated the User access token. Before making requests to the Purchase Request API, you must obtain an access token from the Authentication API.

The response will include an access_token field, which contains your access token. For subsequent calls, you will need to include this access token in the Authorization header of your calls. An id_token will be also included in the response. In order to retrieve the unique ID for your user, you will have to decode this id_token at jwt.io. You will need this ID in order to post Purchase Requests.

LOCATE

User Locations v4

Important: This API is currently in pre-release status and is only available to approved early access participants. The API is under development and might change before being generally released. To become an early access participant, contact your SAP Concur Representative.

Overview

The goal of this API is to allow customers and third party vendors to add their traveler's location data to Concur Locate so it can be utilized locate and contact travelers to address their duty of care requirements.

This API supports POST only.

Limitations: This API is available only in the North America and EMEA Data Centers.

Products and Editions

Scope Usage

Required Scopes:

Name Description Endpoint
locate.location.read Get user location information. POST
locate.location.write Post user location information. POST

Dependencies

None.

Access Token Usage

This API supports company level access tokens.

POST Endpoint

The service is a POST call adhering to the following steps:

Request

URI

Template
POST https://us.api.concursolutions.com//locate/api/v4/user/locations

Headers

Payload

-

Response

Status Codes

Headers

Payload

-

Example

Mobile and Mobile Country Code Valid Combinations

Example with country code for South Africa (country Code: ZA)

Country Code Mobile Number
Empty 7160986233
JP 800122334
81 800122334

A new field partiallyProcessedTransactions is introduced in the response to cater to the following invalid mobile scenarios. * Mobile number is not valid for the country derived based on details provided for traveller * A well formed mobile number could not be derived using the mobile provided

Request

Cancel request without location and user fields (minimal request)
POST https://{baseURI}/locate/api/v4/user/locations
Content-Type: application/json
Accept: application/json
Authorization: Bearer {token}
{
  "userLocations": [
    {
      "client": {
        "id": "UL_CLI"
      },
      "sourcePartner": {
        "id": "SP",
        "name": "Source Partner",
        "description": "Source Partner"
      },
      "transaction": {
        "transactionId": "AAAAAA",
        "createdDate": "2018-08-06T12:05",
        "transactionType": "Cancel"
      }
    }
  ]
}

Response

200 OK
date: Mon, 15 May 2018 14:28:07 GMT
content-length: 20
content-type: application/json
{
    "processedTransactions": {
        "AAAAAA" : "Successfully Processed"
    },
    "unprocessedTransactions": {
    },
    "partiallyProcessedTransactions": {
    }
}

Request

Add request
POST https://{baseURI}/locate/api/v4/user/locations
Content-Type: application/json
Accept: application/json
Authorization: Bearer {token}
{
  "userLocations": [
    {
      "client": {
        "id": "UL_CLI",
        "firstSubLevel": "",
        "secondSubLevel": ""
      },
      "users": [
        {
          "visitorId": 22,
          "firstName": "Test",
          "lastName": "TEST3",
          "email": "test.test3@abcd.com",
          "employeeId": "abc333",
          "mobileCountryCode": "27",
          "mobile": "7160981138",
          "optedIn": true,
          "concurLoginId": "",
          "affiliation": "Student"
        },
        {
          "visitorId": 23,
          "firstName": "Test",
          "lastName": "TEST4",
          "email": "test.test4@abcd.com",
          "employeeId": "abc334",
          "mobileCountryCode": "US",
          "mobile": "2125551138",
          "optedIn": true,
          "concurLoginId": "",
          "affiliation": "Student"
        }
      ],
      "locations": [
        {
          "locationId": 0,
          "locationAddress": "",
          "locationName": "SomeLocation",
          "locationDescription": "",
          "locationLatitude": "",
          "locationLongitude": "",
          "locationIataCode": "LHR",
          "startDate": "2018-09-01T12:07",
          "endDate": "2018-09-02T12:07",
          "timezoneId": "Europe/London",
          "locationPhone": "",
          "visitorId": [
            22,23
          ]
        }
      ],
      "sourcePartner": {
        "id": "SP",
        "name": "Source Partner",
        "description": "Source Partner"
      },
      "transaction": {
        "transactionId": "ASDFGH",
        "createdDate": "2018-08-06T12:05",
        "transactionType": "Add"
      }
    }
  ]
}

Response

200 OK
date: Mon, 15 May 2018 14:28:07 GMT
content-length: 20
content-type: application/json
{
    "processedTransactions": {
        "ASDFGH" : "Successfully Processed"
    },
    "unprocessedTransactions": {
    },
    "partiallyProcessedTransactions": {
    }
}

Request

Add request - mobile phone variation
POST https://{baseURI}/locate/api/v4/user/locations
Content-Type: application/json
Accept: application/json
Authorization: Bearer {token}
{
  "userLocations": [
    {
      "client": {
        "id": "UL_CLI",
        "firstSubLevel": "",
        "secondSubLevel": ""
      },
      "users": [
        {
          "visitorId": 22,
          "firstName": "Test",
          "lastName": "TEST3",
          "email": "test.test3@abcd.com",
          "employeeId": "abc333",
          "mobileCountryCode": "",
          "mobile": "+(27)7160981138",
          "optedIn": true,
          "concurLoginId": "",
          "affiliation": "Student"
        },
        {
          "visitorId": 23,
          "firstName": "Test",
          "lastName": "TEST4",
          "email": "test.test4@abcd.com",
          "employeeId": "abc334",
          "mobileCountryCode": "US",
          "mobile": "2125551138",
          "optedIn": true,
          "concurLoginId": "",
          "affiliation": "Student"
        }
      ],
      "locations": [
        {
          "locationId": 0,
          "locationAddress": "",
          "locationName": "SomeLocation",
          "locationDescription": "",
          "locationLatitude": "",
          "locationLongitude": "",
          "locationIataCode": "LHR",
          "startDate": "2018-09-01T12:07",
          "endDate": "2018-09-02T12:07",
          "timezoneId": "Europe/London",
          "locationPhone": "",
          "visitorId": [
            22,23
          ]
        }
      ],
      "sourcePartner": {
        "id": "SP",
        "name": "Source Partner",
        "description": "Source Partner"
      },
      "transaction": {
        "transactionId": "ASDFGH",
        "createdDate": "2018-08-06T12:05",
        "transactionType": "Add"
      }
    }
  ]
}

Response

200 OK
date: Mon, 15 May 2018 14:28:07 GMT
content-length: 20
content-type: application/json
{
    "processedTransactions": {
        "ASDFGH" : "Successfully Processed"
    },
    "unprocessedTransactions": {
    },
    "partiallyProcessedTransactions": {
    }
}

Request

Add request - invalid mobile phone variation
POST https://{baseURI}/locate/api/v4/user/locations
Content-Type: application/json
Accept: application/json
Authorization: Bearer {token}
{
  "userLocations": [
    {
      "client": {
        "id": "UL_CLI",
        "firstSubLevel": "",
        "secondSubLevel": ""
      },
      "users": [
        {
          "visitorId": 22,
          "firstName": "Test",
          "lastName": "TEST3",
          "email": "test.test3@abcd.com",
          "employeeId": "abc333",
          "mobileCountryCode": "",
          "mobile": "+(27)7160981138",
          "optedIn": true,
          "concurLoginId": "",
          "affiliation": "Student"
        },
        {
          "visitorId": 23,
          "firstName": "Test",
          "lastName": "TEST4",
          "email": "test.test4@abcd.com",
          "employeeId": "abc334",
          "mobileCountryCode": "US",
          "mobile": "0005551138",
          "optedIn": true,
          "concurLoginId": "",
          "affiliation": "Student"
        }
      ],
      "locations": [
        {
          "locationId": 0,
          "locationAddress": "",
          "locationName": "SomeLocation",
          "locationDescription": "",
          "locationLatitude": "",
          "locationLongitude": "",
          "locationIataCode": "LHR",
          "startDate": "2018-09-01T12:07",
          "endDate": "2018-09-02T12:07",
          "timezoneId": "Europe/London",
          "locationPhone": "",
          "visitorId": [
            22,23
          ]
        }
      ],
      "sourcePartner": {
        "id": "SP",
        "name": "Source Partner",
        "description": "Source Partner"
      },
      "transaction": {
        "transactionId": "ASDFGH",
        "createdDate": "2018-08-06T12:05",
        "transactionType": "Add"
      }
    }
  ]
}

Response

200 OK
date: Mon, 15 May 2018 14:28:07 GMT
content-length: 20
content-type: application/json
{
    "processedTransactions": {
    },
    "unprocessedTransactions": {
    },
    "partiallyProcessedTransactions": {
        "ASDFGH": "Partially processed the transactions : [Incorrect mobile for [23] ]"
    }
}

Request

Add request - unprocessed transaction
POST https://{baseURI}/locate/api/v4/user/locations
Content-Type: application/json
Accept: application/json
Authorization: Bearer {token}
{
  "userLocations": [
    {
      "client": {
        "id": "UL_CLI",
        "firstSubLevel": "",
        "secondSubLevel": ""
      },
      "users": [
        {
          "visitorId": 22,
          "firstName": "Test",
          "lastName": "TEST3",
          "email": "test.test3@abcd.com",
          "employeeId": "abc333",
          "mobileCountryCode": "",
          "mobile": "+(27)7160981138",
          "optedIn": true,
          "concurLoginId": "",
          "affiliation": "Student"
        },
        {
          "visitorId": 23,
          "firstName": "Test",
          "lastName": "TEST4",
          "email": "test.test4@abcd.com",
          "employeeId": "abc334",
          "mobileCountryCode": "US",
          "mobile": "asdfrgh",
          "optedIn": true,
          "concurLoginId": "",
          "affiliation": "Student"
        }
      ],
      "locations": [
        {
          "locationId": 0,
          "locationAddress": "",
          "locationName": "SomeLocation",
          "locationDescription": "",
          "locationLatitude": "",
          "locationLongitude": "",
          "locationIataCode": "LHR",
          "startDate": "2018-09-01T12:07",
          "endDate": "2018-09-02T12:07",
          "timezoneId": "Europe/London",
          "locationPhone": "",
          "visitorId": [
            22,23
          ]
        }
      ],
      "sourcePartner": {
        "id": "SP",
        "name": "Source Partner",
        "description": "Source Partner"
      },
      "transaction": {
        "transactionId": "ASDFGH",
        "createdDate": "2018-08-06T12:05",
        "transactionType": "Add"
      }
    }
  ]
}

Response

200 OK
date: Mon, 15 May 2018 14:28:07 GMT
content-length: 20
content-type: application/json
{
    "processedTransactions": {
    },
    "unprocessedTransactions": {
        "ASDFGH": "Invalid mobile details found for transaction [ASDFGH]. Skipping transaction "
    },
    "partiallyProcessedTransactions": {
    }
}

Schema

Name Type Format Description
UserLocations object UserLocations Required Contains the Client, Users, Locations, SourcePartner and Transaction.
Client object Client Required This indicates which entity within the organization the traveler belongs to.
Users object Users Required This is the users' information. This will be used to either create a new traveler or to match with an existing traveler.
Locations object Locations Required This is the users' location information. Multiple locations can be passed for a single user.
SourcePartner object SourcePartner Required This is used to identify your application. This information will be provided to you in advance.
Transaction object Transaction Required Whether this transaction adds or cancels itineraries/locations.

Client

This indicates which entity within the organization the traveler belongs to. This will vary by client. You will be provided with a list of the applicable agencies for each customer.

Name Type Format Description
Id string - Required This maps to the top level corporation. Maximum length: 36
firstSubLevel string - This is the child corporation i.e one level below the top level corporation. Maximum length: 36
secondSubLevel string - This is the sub level of the child corporation (firstsublevel). Maximum length: 36

Users

This information will be used to match or create a new user. Either login ID or email address must be provided. If an existing user is not found for the login ID or email, one will be created.

Name Type Format Description
visitorId long - Required This is a unique identifier for the user generated by your application. Maximum length: 10
firstName string - Required The first name of the user. Maximum length: 100
lastName string - Required The last name of the user. Maximum length: 100
email string - Either email or concurLoginId must be provided Maximum length: 255
employeeId string - Optional field to indicate the employee ID of the user. Maximum length: 19
mobileCountryCode string - Either ISO Alpha-2 code or International Calling Codes (4 digits). Maximum length: 4
mobile string - The contact number of the user. Maximum length: 10
optedIn boolean - If true, indicates if the user has chosen to receive messages via SMS or text.
concurLoginId string - Either email or concurLoginId must be provided
affiliation string - Used to indicate the type of traveler (e.g. employee, student, faculty). Maximum length: 128

Locations

This section includes information about the traveler's future or current location. Either the location latitude and longitude or the IATA (airport) code must be present. If both are present, the latitude and longitude take precedence.

Name Type Format Description
locationId string - Identifier of the travel location.
locationAddress string - Address of the travel location. Maximum length: 512
locationName string - Name of the travel location. Maximum length: 100
locationDescription string - A short description of the travel location. Maximum length: 100
locationPhone string - Contact details of the travel location. Maximum length: 50
locationLatitude string - Either locationIATACode or locationLatitude/locationLongitude must be provided
locationLongitude string - Either locationIATACode or locationLatitude/locationLongitude must be provided
locationIATACode string - Either locationIATACode or locationLatitude/locationLongitude must be provided The three character IATA airport code. Maximum length: 3
startDate string YYYY-MM-DDTHH:MM Required Traveler's arrival date. Maximum length: 16
endDate string YYYY-MM-DDTHH:MM Required Traveler's departure date. Maximum length: 16
timezoneId string - Required Maximum length: 60
visitorID string - This corresponds to the visitorId provided in the Users schema. IDs present in this array must be present in the Users schema. Maximum length: 10

Source Partner

This information will be provided to you along with your client ID and secret.

Name Type Format Description
Id string - Required This will provide to clients similar to the Client ID. Maximum length: 2
name string - The name of the source provider. Example: Source Provider1. Maximum length: 100
description string - A short description of the source provider. Maximum length: 100

Transaction

Itineraries can be added or cancelled. This section allows you to indicate whether this is an addition of a new itinerary or cancellation of an existing itinerary. A cancellation request is for canceling the itinerary completely in our system and if there are any updates to the existing itineraries then it needs to be resent using the same booking or transaction ID.

Name Type Format Description
transactionId string - Required This is a unique identifier generated by your application for the request. Maximum length: 5
createdDate string YYYY-MM-DDTHH:MM Required Maximum length: 16
transactionType string - Required Add is indicative of creating a new itinerary or updating an existing itinerary. Cancel means removing the itinerary. Cancel works only on future dated itineraries. Supported values: Add, Cancel

NOTIFICATIONS

Partner Notifications v4

The purpose of this API is to provide SAP Concur partners the ability to message users through the web and mobile product.

Sample use case: A business traveller starts a travel booking. That user is notified that a visa is required for their trip.

Process Flow

Process flow for notifications

Products and Editions

Scope Usage

Name Description Endpoint
notifications.messages.writeonly Write messages to the notifications platform POST

Dependencies

Access Token Usage

A Company access token (JWT) is required for this endpoint.

Send a message

The endpoint provides a way for SAP Concur partners to message users and notify them. Partners will provide the identifier of the pre-configured message template, along with the data to apply to the message.

Scopes

notifications.messages.writeonly - Refer to Scope Usage for full details.

Request

URI

Template
https://us.api.concursolutions.com/notifications/v4/messages/{userId}/session
Parameters
Name Type Format Description
userId string - Required The userId of the user to whom the notification should be sent.

Headers

Payload

Response

Status Codes

Headers

Payload

Example

Request

POST https://us.api.concursolutions.com/notifications/v4/messages/0E6BD8D8-A020-43C6-BBEC-B67A7021FF1C
/session
Accept: application/json
Authorization: Bearer {JWT}
content-type: application/json
{
   "sessionId": "D5B80C53-A4D2-4949-8462-D41655F246E2",
   "templateId": "template-name",
   "context": {
     "url": "https://www.example.com/foo"
   }
}

Response

HTTP/1.1 200 OK
concur-correlationid: 848618e7-5747-4970-bda7-fc7baf251f88
Content-Type: application/json; charset=utf-8
Date: Thu, 24 Jan 2019 01:31:47 GMT

Schema

Name Type Format Description
sessionId string - Required The unique ID of the session
templateId string - Required The template identifier of the message
context object context Contains additional information required for the template

Context

Name Type Format Description
url string - The context URL to apply to the template. Please contact SAP Concur to add domains to the approved list.

Error

Name Type Format Description
errorId string - The unique ID of the error
errorCode string - The error code
errorMessage string - A message describing the error
errors array error An array of errors. Note: this points to this schema as errors can nest.

PROFILE

Identity v4

Overview

The Identity v4 service is designed to create, update, and read user’s core identity profile. This service is also available to look up the SAP Concur UUID to access any v4 API for a single user only.

This API is used to help provision and manage user accounts and profile details across multiple SAP Concur products, including Expense, Invoice, Request, Travel, and TripIt.

Limitations: Only the GET operations are available at this time. This API is not available in the China Data Center. This API is only available to partners who have been granted access by SAP Concur. Access to this documentation does not provide access to the API.

Products and Editions

Scope Usage

Name Description Endpoint
identity.user.ids.read Read user ID data. GET
identity.user.core.read Read user core data. GET
identity.user.coresensitive.read Read core sensitive data. GET
identity.user.enterprise.read Read user enterprise data. GET
identity.user.coreenterprise.writeonly Write access to all core and enterprise fields except externalID. PUT, POST, PATCH
identity.user.externalID.writeonly Write access to externalID only. PUT, POST, PATCH

For more information on scope usage and mapping, please see the Identity v4 Scope Mapping page.

Dependencies

None.

Access Token Usage

This API supports only company level access tokens.

Retrieve Users

Retrieves all users of a given company. The filter operation can be used to fetch a unique user’s identity information.

Request

URI

Template
GET https://us.api.concursolutions.com/profile/identity/v4/Users
GET https://us.api.concursolutions.com/profile/identity/v4/Users?count=20
GET https://us.api.concursolutions.com/profile/identity/v4/Users/<UUID>
GET https://us.api.concursolutions.com/profile/identity/v4/Users?filter=attributes eq "value"
Parameters
Name Type Format Description
filter string - The filter string used to request a subset of resources.
attributes object - A multi-valued list of strings indicating the names of resource attributes to return in the response. It is comma delimited.
userName string user@domain The requested user's username. NOTE: The userName must be unique across all SAP Concur products. If a userName is currently in use in any SAP Concur product, it cannot be assigned again unless the original occurrence is changed. For example, assume that a userName was assigned in error. That userName can only be used again if an admin (either manually or via import) renames the original occurrence, allowing the userName to be used again. The following characters cannot be used as a value for this record: % [ # ! * & ( ) ~ ' { ^ } \ / ? > < , ; : " + = ], and pipe.
companyId string - Required, if employeeNumber is used The ID of the company the user belongs to.
employeeNumber string - Required, if companyId is used User's employee number.
externalId string - User’s external ID.
excludedAttributes string - A multi-valued list of strings indicating the names of resource attributes to be removed from the default set of attributes to return.
startIndex string - The 1-based index of the first query result. Default: 1
count string - The desired maximum number of query results per page. Maximum count: 100. Default: 10

Headers

Payload

None.

Response

Status Codes

Headers

Payload

User Schema

Example

Request

GET https://us.api.concursolutions.com/profile/identity/v4/users/
Accept: application/json
Authorization: BEARER {token}

Response

200 OK
Content-Type: application/json
{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 107705,
  "startIndex": 1,
  "itemsPerPage": 20,
  "Resources": [
    { User 1 },
    {User 2},
    {User 20}
  ]
}

Retrieve a User's Identity Profile

Retrieves a unique user based on the user’s UUID.

Request

URI

Template
GET https://us.api.concursolutions.com/profile/identity/v4/Users/
Parameters
Name Type Format Description
id string - Requested user's UUID.

Headers

Payload

None.

Response

Status Codes

Headers

Payload

User Schema

Example

Request

GET https://us.api.concursolutions.com/profile/identity/v4/Users/
Accept: application/json
Authorization: BEARER {token}

Response

200 OK
Content-Type: application/json
{
  "active": true,
  "addresses": [
    {
      "country": "string",
      "locality": "string",
      "postalCode": "string",
      "region": "string",
      "streetAddress": "string",
      "type": "work"
    }
  ],
  "dateOfBirth": "string",
  "displayName": "string",
  "emails": [
    {
      "dateAdded": "string",
      "dateVerified": "string",
      "notifications": true,
      "type": "work",
      "value": "string",
      "verified": true
    }
  ],
  "emergencyContacts": [
    {
      "country": "string",
      "emails": [
        "string"
      ],
      "locality": "string",
      "name": "string",
      "phones": [
        "string"
      ],
      "postalCode": "string",
      "region": "string",
      "relationship": "Spouse",
      "streetAddress": "string"
    }
  ],
  "entitlements": [
    "Expense"
  ],
  "externalId": "string",
  "gender": "Male",
  "id": "string",
  "localeOverrides": {
    "preference24Hour": "h:mm AM/PM",
    "preferenceCurrencySymbolLocation": "BeforeAmount",
    "preferenceDateFormat": "mm/dd/yyyy",
    "preferenceDefaultCalView": "day",
    "preferenceDistance": "mile",
    "preferenceEndDayViewHour": 0,
    "preferenceFirstDayOfWeek": "Monday",
    "preferenceHourMinuteSeparator": ":",
    "preferenceNegativeCurrencyFormat": "-100",
    "preferenceNegativeNumberFormat": "-100",
    "preferenceNumberFormat": "1,000.00",
    "preferenceStartDayViewHour": 0
  },
  "meta": {},
  "name": {
    "familyName": "string",
    "formatted": "string",
    "givenName": "string",
    "hasNoMiddleName": true,
    "honorificPrefix": "Miss",
    "honorificSuffix": "Jr.",
    "legalName": "string",
    "middleInitial": "string",
    "middleName": "string"
  },
  "nickName": "string",
  "phoneNumbers": [
    {
      "display": "string",
      "notifications": true,
      "operatingSystem": "Android Phone",
      "primary": true,
      "type": "work",
      "value": "string"
    }
  ],
  "preferredLanguage": "string",
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "timezone": "string",
  "title": "string",
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "companyId": "string",
    "costCenter": "string",
    "department": "string",
    "division": "string",
    "employeeNumber": "string",
    "manager": {
      "$ref": "string",
      "displayName": "string",
      "employeeNumber": "string",
      "value": "string"
    },
    "orgUnit": "string",
    "organization": "string",
    "self": {
      "$ref": "string",
      "displayName": "string",
      "employeeNumber": "string",
      "value": "string"
    },
    "startDate": "string",
    "terminationDate": "string"
  },
  "userName": "string"
}

Create a User's Identity Profile

Important: This API is currently in pre-release status and is only available to approved early access participants. The API is under development and might change before being generally released. To become an early access participant, contact your SAP Concur Representative.

Creates a user's identity profile.

Request

URI

Template
POST https://us.api.concursolutions.com/profile/identity/v4/Users
Parameters
Name Type Format Description
user string - The user identity to create.

Headers

Payload

None.

Response

Status Codes

Headers

Payload

User Schema

Example

Request

{
  "userName": "SAPDemoUser_User222@example.com",
  "active": true,
   "name": {
      "familyName": "SAPDemoUser",
      "givenName": "User222"
   },
  "emails": [
    {
        "value": "SAPDemoUser_User222@example.com"
    }
  ],
   "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
      "companyId": "aa076ada-80a9-4f57-8e98-9300b1c3171d"
    }
}

Response

{
  "meta": {
    "resourceType": "User",
    "created": "2020-08-14T23:07:02.000739Z",
    "lastModified": "2020-08-14T23:07:02.000739Z",
    "version": 0,
    "location": "https://us.api.concursolutions.com/profile/identity/v4/users/b38316e0-e2f6-48c8-bb3b-193d4faef578"
  },
  "displayName": "User222",
  "name": {
    "familyName": "SAPDemoUser",
    "givenName": "User222",
    "formatted": "SAPDemoUser, User222 "
  },
  "phoneNumbers": [],
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
  ],
  "active": true,
  "id": "b38316e0-e2f6-48c8-bb3b-193d4faef578",
  "emails": [
    {
      "value": "SAPDemoUser_User222@example.com"
    }
  ],
  "userName": "SAPDemoUser_User222@example.com",
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "companyId": "aa076ada-80a9-4f57-8e98-9300b1c3171d"
  }
}

Update a User's Identity Profile

Important: This API is currently in pre-release status and is only available to approved early access participants. The API is under development and might change before being generally released. To become an early access participant, contact your SAP Concur Representative.

Updates applicable attributes in the user's identity profile.

Request

URI

Template
PATCH https://us.api.concursolutions.com/profile/identity/v4/Users/UUID
Parameters
Name Type Format Description
id string - The user's UUID.

Headers

Payload

None.

Response

Status Codes

Headers

Payload

User Schema

Example

Request

{
    "Operations": [
        {
            "op": "add",
    "path" : "externalId",
            "value": "123-222"
                }
            ]
 }

Response

{
  "localeOverrides": {
    "preferenceEndDayViewHour": 20,
    "preferenceFirstDayOfWeek": "Sunday",
    "preferenceDateFormat": "mm/dd/yyyy",
    "preferenceCurrencySymbolLocation": "BeforeAmount",
    "preferenceHourMinuteSeparator": ":",
    "preferenceDefaultCalView": "month",
    "preference24Hour": "H:mm",
    "preferenceNumberFormat": "1,000.00",
    "preferenceStartDayViewHour": 8,
    "preferenceNegativeCurrencyFormat": "-100"
  },
"title": null,
  "addresses": [
    {
      "country": "US",
      "streetAddress": null,
      "postalCode": null,
      "locality": null,
      "type": "home",
      "region": null
    },
    {
      "country": "US",
      "streetAddress": null,
      "postalCode": null,
      "locality": null,
      "type": "work",
      "region": null
    }
  ],
  "timezone": "America/New_York",
  "meta": {
    "resourceType": "User",
    "created": "2020-08-14T23:07:02.000739Z",
    "lastModified": "2020-08-14T23:07:04.000900Z",
    "version": 2,
    "location": "https://us.api.concursolutions.com/profile/identity/v4/users/b38316e0-e2f6-48c8-bb3b-193d4faef578"
  },
  "displayName": "User222",
  "name": {
    "honorificSuffix": null,
    "hasNoMiddleName": true,
    "formatted": "SAPDemoUser, User222 ",
    "familyName": "SAPDemoUser",
    "givenName": "User222",
    "honorificPrefix": null,
    "middleName": null
  },
  "phoneNumbers": [],
  "emergencyContacts": [
    {
      "country": null,
      "streetAddress": null,
      "postalCode": null,
      "name": null,
      "locality": null,
      "phones": [],
      "region": null,
      "relationship": "Other"
    }
  ],
  "preferredLanguage": "en-US",
  "dateOfBirth": null,
  "nickName": null,
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
  ],
  "externalId": "123-222",
  "active": true,
  "id": "b38316e0-e2f6-48c8-bb3b-193d4faef578",
  "gender": null,
  "emails": [],
  "userName": "SAPDemoUser_User222@example.com",
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "terminationDate": null,
    "companyId": "aa076ada-80a9-4f57-8e98-9300b1c3171d",
    "manager": null,
    "costCenter": null,
    "orgUnit": null,
    "startDate": "2020-08-14T23:07:00.000",
    "employeeNumber": null
  }
}

Replace a User's Identity Profile

Important: This API is currently in pre-release status and is only available to approved early access participants. The API is under development and might change before being generally released. To become an early access participant, contact your SAP Concur Representative.

Replaces a user's identity profile.

Request

URI

Template
PUT https://us.api.concursolutions.com/profile/identity/v4/Users/UUID
Parameters
Name Type Format Description
id string - The user's UUID.
user string - The user identity to update.

Headers

Payload

User Schema

Response

Status Codes

Headers

Payload

User Schema

Example

Request

{
  "active": true,
  "addresses": [
    {
      "country": "string",
      "locality": "string",
      "postalCode": "string",
      "region": "string",
      "streetAddress": "string",
      "type": "work"
    }
  ],
  "dateOfBirth": "string",
  "displayName": "string",
  "emails": [
    {
      "dateAdded": "string",
      "dateVerified": "string",
      "notifications": true,
      "type": "work",
      "value": "string",
      "verified": true
    }
  ],
  "emergencyContacts": [
    {
      "country": "string",
      "emails": [
        "string"
      ],
      "locality": "string",
      "name": "string",
      "phones": [
        "string"
      ],
      "postalCode": "string",
      "region": "string",
      "relationship": "Spouse",
      "streetAddress": "string"
    }
  ],
  "entitlements": [
    "Expense"
  ],
  "externalId": "string",
  "gender": "Male",
  "id": "string",
  "localeOverrides": {
    "preference24Hour": "h:mm AM/PM",
    "preferenceCurrencySymbolLocation": "BeforeAmount",
    "preferenceDateFormat": "mm/dd/yyyy",
    "preferenceDefaultCalView": "day",
    "preferenceDistance": "mile",
    "preferenceEndDayViewHour": 0,
    "preferenceFirstDayOfWeek": "Monday",
    "preferenceHourMinuteSeparator": ":",
    "preferenceNegativeCurrencyFormat": "-100",
    "preferenceNegativeNumberFormat": "-100",
    "preferenceNumberFormat": "1,000.00",
    "preferenceStartDayViewHour": 0
  },
  "meta": {},
  "name": {
    "academicTitle": [
      "Dr."
    ],
    "familyName": "string",
    "familyNamePrefix": "string",
    "formatted": "string",
    "givenName": "string",
    "hasNoMiddleName": true,
    "honorificPrefix": "Miss",
    "honorificSuffix": "Jr.",
    "legalName": "string",
    "middleInitial": "string",
    "middleName": "string"
  },
  "nickName": "string",
  "phoneNumbers": [
    {
      "display": "string",
      "notifications": true,
      "operatingSystem": "Android Phone",
      "primary": true,
      "type": "work",
      "value": "string"
    }
  ],
  "preferredLanguage": "string",
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "timezone": "string",
  "title": "string",
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "companyId": "string",
    "costCenter": "string",
    "department": "string",
    "division": "string",
    "employeeNumber": "string",
    "manager": {
      "$ref": "string",
      "displayName": "string",
      "employeeNumber": "string",
      "value": "string"
    },
    "orgUnit": "string",
    "organization": "string",
    "self": {
      "$ref": "string",
      "displayName": "string",
      "employeeNumber": "string",
      "value": "string"
    },
    "startDate": "string",
    "terminationDate": "string"
  },
  "userName": "string"
}

Response

{
  "meta": {
    "resourceType": "User",
    "created": "2020-08-14T23:07:02.000739Z",
    "lastModified": "2020-08-14T23:07:02.000739Z",
    "version": 0,
    "location": "https://us.api.concursolutions.com/profile/identity/v4/users/b38316e0-e2f6-48c8-bb3b-193d4faef578"
  },
  "displayName": "User222",
  "name": {
    "familyName": "SAPDemoUser",
    "givenName": "User222",
    "formatted": "SAPDemoUser, User222 "
  },
  "phoneNumbers": [],
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
  ],
  "active": true,
  "id": "b38316e0-e2f6-48c8-bb3b-193d4faef578",
  "emails": [
    {
      "value": "SAPDemoUser_User222@example.com"
    }
  ],
  "userName": "SAPDemoUser_User222@example.com",
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "companyId": "aa076ada-80a9-4f57-8e98-9300b1c3171d"
  }
}

Schema

User

Name Type Format Description
active boolean true/false Required If true, the user is active.
addresses object - A physical mailing address for this user. Examples: work, home, other
addresses.country string - A two-letter country code defined in ISO 3166-1 alpha-2.
addresses.locality string - The city or locality.
addresses.postalCode string - The zip code or postal code.
addresses.region string - The state or region.
addresses.streetAddress string - The full street address component, which may include house number, street name, P.O. box, and multi-line extended street address information.
addresses.type string - A label indicating the function of the address. Examples: work, home
dateOfBirth string YYYY-MM-DD The user's date of birth.
displayName string - The name of the user, suitable for public display.
emails object - Required Email addresses for the user. The value should be canonicalized by the service provider.
dateAdded string - The date and time the email was added to the user's profile.
dateVerified string - The date and time the email was verified.
emails.notifications boolean true/false If true, notifications have been opted-in for emails.
emails.type string - A label indicating the attribute's function. Examples: work, home
emails.value string - Required Email address value.
emails.verified boolean true/false If true, the email has been verified by the user.
emergencyContacts object - Emergency contact information for the user.
emergencyContacts.country string - A two-letter country code defined in ISO 3166-1 alpha-2.
emergencyContacts.emails string - Emails of the emergency contact.
emergencyContacts.locality string - The city or locality of the emergency contact.
emergencyContacts.name string - Required The emergency contact's name.
emergencyContacts.phones string - Phone numbers of the emergency contact.
emergencyContacts.postalCode string - The zip code or postal code of the emergency contact.
emergencyContacts.region string - The state or region of the emergency contact.
emergencyContacts.relationship string - Required The emergency contact's relationship to the user. Supported values: Spouse, Brother, Parent, Sister, Life Partner, Other
emergencyContacts.streetAddress string - The full street address component, which may include house number, street name, P.O. box, and multi-line extended street address information.
entitlements string - The features enabled for the user. Supported values: Expense, Invoice, Locate, Request, Travel
externalId string - User identifier from the provisioning client.
gender string - The user's gender.
id string - Required. Read Only Unique identifier for the user, also known as the UUID.
localeOverrides object - Read Only Support for users who want to override locale settings.
localeOverrides.preference24Hour string - Preferred 24 hour format for the user. Supported values: h:mm AM/PM, H:mm
localeOverrides.preferenceCurrencySymbolLocation string - Preferred currency symbol location for the user. Supported values: BeforeAmount, AfterAmount
localeOverrides.preferenceDateFormat string - Preferred date format for the user.
localeOverrides.preferenceDefaultCalView string - Preferred default calendar view for the user. Supported values: day, week, month
localeOverrides.preferenceDistance string - Preferred distance metric. Supported values: mile, km
localeOverrides.preferenceEndDayViewHour integer - Preferred hour setting for the end of day. Supported values: 0-23
localeOverrides.preferenceFirstDayOfWeek string - Preferred first day of the week for the user.
localeOverrides.preferenceHourMinuteSeparator string - Preferred separator between hour and minute. Supported values: :, .
localeOverrides.preferenceNegativeCurrencyFormat string - Preferred negative currency format for the user.
localeOverrides.preferenceNegativeNumberFormat string - Preferred negative number format for the user.
localeOverrides.preferenceNumberFormat string - Preferred number format for the user.
localeOverrides.preferenceStartDayViewHour integer - Preferred start of day for the user, from 1.
meta object - Read Only
name object - Required The user's name.
name.academicTitle string - Title signifying level of academic achievement.
familyName string - Required The family or last name of the user.
name.familyName string - Required The family or last name of the user.
name.familyNamePrefix string - The family name prefix of the user, if applicable.
name.formatted string - The full name of the user, formatted for display. Example: Jensen, Barbara Jane
name.givenName string - Required The given or first name of the user.
name.hasNoMiddleName boolean true/false If true, the user has a middle name.
name.honorificPrefix string - The honorific or title prefix(es) of the user.
name.honorificSuffix string - The honorific suffix(es) of the user.
name.legalName string - The legal name of the user.
name.middleInitial string - The middle initial of the user, if applicable.
name.middleName string - The middle name(s) of the user, if applicable.
name.nickName string - The casual way to address the user. This attribute should not be used to represent a user's username.
phoneNumbers object - Phone numbers for the user. The value should be canonicalized by the service provider according to the format specified in RFC 3966. Duplicates are not allowed for types other than mobile.
phoneNumbers.display string - A human-readable phone number for display.
phoneNumbers.notifications boolean true/false If true, notifications have been opted in for phone numbers. This is only available for mobile phone numbers.
phoneNumbers.operatingSystem string - The operating system of the device, when the phone is a cellphone type.
phoneNumbers.primary boolean true/false If true, this is the primary mobile device. This is only available for mobile phone numbers. One mobile phone number must be set as the primary number and only one phone number can be set to primary at a time.
phoneNumbers.type string - A label indicating the attribute's function. Examples: work, home, mobile
phoneNumbers.value string - Required The phone number value.
preferredLanguage string - Indicates the user's preferred written or spoken language.
timezone string - The user's time zone in the Olson time zone database format. Example: America/Los_Angeles
title string - The user's job title in the company.
companyId string - Required. Immutable The SAP Concur ID of the company.
costCenter string - The employee cost center for product. The value of this parameter is provisioned and is not related to the Concur Expense costCenter.
department string - Client supplied department name. The value of this parameter is provisioned and is not related to the Concur Expense department.
division string - Client supplied division name. The value of this parameter is provisioned and is not related to the Concur Expense division.
employeeNumber string - Client supplied employee number within the company, unique for the company.
manager object - The manager of this user.
$ref string - The URI of the SCIM resource representing the referenced user.
displayName string - Read Only The referenced user's display name.
employeeNumber string - The referenced user's employee number, if it is an Enterprise user.
value string - The referenced user's UUID.
orgUnit string - Client supplied org unit name. The value of this parameter is provisioned and is not related to the Concur Expense orgUnit.
organization string - Read Only The company name.
self object - A reference to this user.
$ref string - The URI of the SCIM resource representing the referenced user.
displayName string - Read Only The referenced user's display name.
employeeNumber string - The referenced user's employee number, if it is an Enterprise user.
value string - The referenced user's UUID.
startDate string YYYY-MM-DD The user's start date.
terminationDate string YYYY-MM-DD The user's termination date.
userName string user@domain Required The name that can be used to login to Concur Travel and Expense. NOTE: The userName must be unique across all SAP Concur products. If a userName is currently in use in any SAP Concur product, it cannot be assigned again unless the original occurrence is changed. For example, assume that a userName was assigned in error. That userName can only be used again if an admin (either manually or via import) renames the original occurrence, allowing the userName to be used again. The following characters cannot be used as a value for this record: % [ # ! * & ( ) ~ ' { ^ } \ / ? > < , ; : " + = ] and pipe

UserList

Name Type Format Description
totalResults integer - The total number of results matching the client query.
itemsPerPage integer - The number of query results returned in a query response page.
startIndex integer - The 1-based index of the first result in the current set of query results.
Resources User - -

Company

Name Type Format Description
active boolean true/false Required If true, the company is active.
addresses object - -
country string - A two-letter country code defined in ISO 3166-1 alpha-2.
locality string - The city or locality of the company address.
postalCode string - The zip code or postal code of the company address.
region string - The state or region of the company address.
streetAddress string - The full street address component, which may include house number, street name, P.O. box, and multi-line extended street address information.
companyDomain string - The company's company domain name.
contact object - -
country string - A two-letter country code defined in ISO 3166-1 alpha-2.
emails string - Emails of the contact.
locality string - The city or locality of the contact.
name string - Required Name of the contact.
phones string - Phone numbers of the contact.
postalCode string - The zip code or postal code of the contact.
region string - The state or region.
streetAddress string - The full street address component, which may include house number, street name, P.O. box, and multi-line extended street address information.
defaultLanguage string - Indicates the default language for the company.
entitlements string - The features enabled for the company. Supported values: Expense, Invoice, Locate, Request, Travel
id string - Required Unique identifier for the company, also known as the company UUID.
internetDomain string - The company's internet domain name.
meta object - -
name string - The name of the company.
schemas string - Read Only
loginPolicy object - -
hideForgotLoginIdLink boolean true/false If true, the Forgot LoginId Link will be hidden.
loginFailureLockoutDuration integer - The duration of the login failure lockout.
loginFailureWindowDuration integer - The window duration of the login failure.
loginFailuresAllowed integer - The amount of login failures allowed.
loginIPRestriction string - The login IP restrictions.
loginOneTimeLinkExpirationLength integer - The length of the one time login expiration link.
loginViaSsoOnly boolean true/false If true, the login is available via SSO only.
passwordPolicy object - -
daysUntilExpiration integer - Number of days until password expiration.
expirePasswordOnUserCreation boolean true/false If true, the password will expire on user creation.
maxLength integer - Maximum length of the password.
minLength integer - Minimum length of the password.
mobileAuthenticationLifetime integer - The mobile session timeout in seconds.
mobileMinLength integer - The minimum length of the password for mobile.
mobileRequiresMixedCase boolean true/false If true, the password will require mixed cases for mobile.
mobileRequiresNonalphanum boolean true/false If true, the password will require non-alphanumeric characters for mobile.
numGenerationsBeforeCanReuse integer - Number of generations before the password can be reused.
numSecurityQuestions integer - The number of required security questions.
numSecurityQuestionsUsersPick integer - The number of security questions users can pick.
passwordResetEmailPolicy string - When the password reset email should be sent. Supported values: never, anyTime, afterFirstLogin
passwordResetSupportEmail string - The from address of the password or PIN reset email.
requiresMixedCase boolean true/false If true, the password will require mixed cases.
requiresNonAlpha boolean true/false If true, the password will requires non-alphabetic characters.
requiresNonAlphanum boolean true/false If true, the password will require non-alphanumeric characters.
requiresNumber boolean true/false If true, the password will require numbers.
requiresSecurityQuestions boolean true/false If true , security questions will be required.
restrictPasswordResetOncePerDay boolean true/false If true, password resets will be limited to once a day.
channels string - -
enabled boolean true/false If true, channels will be enabled.
tenantIdSpend string - The ID of the spend tenant for the company.
tenantIdTravel string - The ID of the travel tenant for the company.

Schema Extension

Name Type Format Description
schema string - Required The string identifier of the extension.
required boolean true/false Required If true, this extension is a required part of the schema.

Resource Type

Name Type Format Description
attributes SchemaExtension - Required The resource's extensions.
description string - Required The resource's description.
endpoint string - Required The resource's HTTP addressable endpoint relative to the base URL. Example: /Users
id string - Required The resource's ID.
name string - Required The resource's name. Example: User
schema string - Required The resource's associated schema.

Authenticated Schemas

Name Type Format Description
description string - Required The description of the authentication schema.
documentationUrl string - Required An HTTP addressable URL pointing to the authentication schema's usage documentation.
name string - Required The common authentication schema name. Example: HTTP Basic
specUrl string - Required An HTTP addressable URL pointing to the authentication schema's specification.

Service Provider Config

Name Type Format Description
authenticationSchemes AuthenticationSchemes - Required Specifies supported authentication schema properties.
bulk ServiceProviderConfigSetting - Required Details about the feature support for the service provider.
changePassword ServiceProviderConfigSetting - Required Details about the feature support for the service provider.
documentationUrl string - Required An HTTP addressable URL pointing to the service provider's help documentation.
etag ServiceProviderConfigSetting - Required Details about the feature support for the service provider.
filter ServiceProviderConfigSetting - Required Details about the feature support for the service provider.
patch ServiceProviderConfigSetting - Required Details about the feature support for the service provider.
sort ServiceProviderConfigSetting - Required Details about the feature support for the service provider.

Service Provider Config Setting

Name Type Format Description
supported boolean true/false If true, the feature is supported.

Concur Error

Name Type Format Description
messages object - Additional messages in case of errors/warnings.
code string - Required The error message code.
message string - The error message description.
schemaPath string - The relative schema path of attribute.
type string - Required The error message type. Supported values: error, warning

Error Response

Name Type Format Description
scimType string - The SCIM detail error keyword.
detail string - The human readable message.
status string - Required The HTTP status code.

Identity v4 Scope Mapping

Important: This API is currently in pre-release status and is only available to approved early access participants. The API is under development and might change before being generally released. To become an early access participant, contact your SAP Concur Representative.

User

Name Scope
active identity.user.core.read, identity.user.coreenterprise.writeonly
addresses identity.user.coresensitive.read, identity.user.coreenterprise.writeonly
country identity.user.coresensitive.read, identity.user.coreenterprise.writeonly
locality identity.user.coresensitive.read, identity.user.coreenterprise.writeonly
postalCode identity.user.coresensitive.read, identity.user.coreenterprise.writeonly
region identity.user.coresensitive.read, identity.user.coreenterprise.writeonly
streetAddress identity.user.coresensitive.read, identity.user.coreenterprise.writeonly
type identity.user.coresensitive.read, identity.user.coreenterprise.writeonly
dateOfBirth identity.user.coresensitive.read, identity.user.coreenterprise.writeonly
displayName identity.user.core.read, identity.user.coreenterprise.writeonly
emails identity.user.coresensitive.read, identity.user.coreenterprise.writeonly
dateAdded identity.user.coresensitive.read, identity.user.coreenterprise.writeonly
dateVerified identity.user.coresensitive.read, identity.user.coreenterprise.writeonly
notifications identity.user.coresensitive.read, identity.user.coreenterprise.writeonly
type identity.user.coresensitive.read, identity.user.coreenterprise.writeonly
value identity.user.coresensitive.read, identity.user.coreenterprise.writeonly
verified identity.user.coresensitive.read, identity.user.coreenterprise.writeonly
emergencyContacts identity.user.coresensitive.read, identity.user.coreenterprise.writeonly
country identity.user.coresensitive.read, identity.user.coreenterprise.writeonly
emails identity.user.coresensitive.read, identity.user.coreenterprise.writeonly
locality identity.user.coresensitive.read, identity.user.coreenterprise.writeonly
name identity.user.core.read, identity.user.coreenterprise.writeonly
phones identity.user.coresensitive.read, identity.user.coreenterprise.writeonly
postalCode identity.user.coresensitive.read, identity.user.coreenterprise.writeonly
region identity.user.coresensitive.read, identity.user.coreenterprise.writeonly
relationship identity.user.coresensitive.read, identity.user.coreenterprise.writeonly
streetAddress identity.user.coresensitive.read, identity.user.coreenterprise.writeonly
entitlements identity.user.enterprise.read, identity.user.coreenterprise.writeonly
externalId identity.user.ids.read, identity.user.externalID.writeonly
gender identity.user.coresensitive.read, identity.user.coreenterprise.writeonly
id identity.user.ids.read, identity.user.core.read
localeOverrides identity.user.core.read, identity.user.coreenterprise.writeonly
preference24Hour identity.user.core.read, identity.user.coreenterprise.writeonly
preferenceCurrencySymbolLocation identity.user.core.read, identity.user.coreenterprise.writeonly
preferenceDateFormat identity.user.core.read, identity.user.coreenterprise.writeonly
preferenceDefaultCalView identity.user.core.read, identity.user.coreenterprise.writeonly
preferenceDistance identity.user.core.read, identity.user.coreenterprise.writeonly
preferenceEndDayViewHour identity.user.core.read, identity.user.coreenterprise.writeonly
preferenceFirstDayOfWeek identity.user.core.read, identity.user.coreenterprise.writeonly
preferenceHourMinuteSeparator identity.user.core.read, identity.user.coreenterprise.writeonly
preferenceNegativeCurrencyFormat identity.user.core.read, identity.user.coreenterprise.writeonly
preferenceNegativeNumberFormat identity.user.core.read, identity.user.coreenterprise.writeonly
preferenceNumberFormat identity.user.core.read, identity.user.coreenterprise.writeonly
preferenceStartDayViewHour identity.user.core.read, identity.user.coreenterprise.writeonly
meta identity.user.core.read, identity.user.coreenterprise.writeonly
name identity.user.core.read, identity.user.coreenterprise.writeonly
academicTitle identity.user.core.read, identity.user.coreenterprise.writeonly
familyName identity.user.core.read, identity.user.coreenterprise.writeonly
familyNamePrefix identity.user.core.read, identity.user.coreenterprise.writeonly
formatted identity.user.core.read, identity.user.coreenterprise.writeonly
givenName identity.user.core.read, identity.user.coreenterprise.writeonly
hasNoMiddleName identity.user.core.read, identity.user.coreenterprise.writeonly
honorificPrefix identity.user.core.read, identity.user.coreenterprise.writeonly
honorificSuffix identity.user.core.read, identity.user.coreenterprise.writeonly
legalName identity.user.core.read, identity.user.coreenterprise.writeonly
middleInitial identity.user.core.read, identity.user.coreenterprise.writeonly
middleName identity.user.core.read, identity.user.coreenterprise.writeonly
nickName identity.user.core.read, identity.user.coreenterprise.writeonly
phoneNumbers identity.user.coresensitive.read, identity.user.coreenterprise.writeonly
display identity.user.coresensitive.read, identity.user.coreenterprise.writeonly
notifications identity.user.coresensitive.read, identity.user.coreenterprise.writeonly
operatingSystem identity.user.coresensitive.read, identity.user.coreenterprise.writeonly
primary identity.user.coresensitive.read, identity.user.coreenterprise.writeonly
type identity.user.coresensitive.read, identity.user.coreenterprise.writeonly
value identity.user.coresensitive.read, identity.user.coreenterprise.writeonly
preferredLanguage identity.user.core.read, identity.user.coreenterprise.writeonly
timezone identity.user.core.read, identity.user.coreenterprise.writeonly
title identity.user.core.read, identity.user.coreenterprise.writeonly
companyId identity.user.enterprise.read, identity.user.coreenterprise.writeonly
costCenter identity.user.enterprise.read, identity.user.coreenterprise.writeonly
department identity.user.enterprise.read, identity.user.coreenterprise.writeonly
division identity.user.enterprise.read, identity.user.coreenterprise.writeonly
employeeNumber identity.user.enterprise.read, identity.user.coreenterprise.writeonly
manager identity.user.enterprise.read, identity.user.coreenterprise.writeonly
$ref identity.user.core.read
displayName identity.user.core.read, identity.user.coreenterprise.writeonly
employeeNumber identity.user.enterprise.read, identity.user.coreenterprise.writeonly
value identity.user.coreenterprise.writeonly
orgUnit identity.user.enterprise.read, identity.user.coreenterprise.writeonly
organization identity.user.enterprise.read, identity.user.coreenterprise.writeonly
self identity.user.enterprise.read, identity.user.coreenterprise.writeonly
$ref identity.user.core.read
displayName identity.user.core.read, identity.user.coreenterprise.writeonly
employeeNumber identity.user.enterprise.read, identity.user.coreenterprise.writeonly
value identity.user.coreenterprise.writeonly
startDate identity.user.enterprise.read, identity.user.coreenterprise.writeonly
terminationDate identity.user.enterprise.read, identity.user.coreenterprise.writeonly
userName identity.user.coreenterprise.writeonly, identity.user.ids.read

REALTIME-LOCATION-INGEST

Realtime Ingest Location

Important: This API is currently in pre-release status and is only available to approved early access participants. The API is under development and might change before being generally released. To become an early access participant, contact your SAP Concur Representative.

Overview

This API provides an endpoint to ingest real time user location information from Rideshare Services.

Regional Availability

https://us.api.concursolutions.com/realtimeingest

Request Headers

Request Payload

Please refer the Schema section for more information regarding each field in the payload.

Response Headers

Response Payload

Name Type Format Description
concur-correlationId String - Concur specific custom field
requestId String - Unique ID for the request
appVersion String - Application version number
message String - Success / Error message
errorDescription Object JSON Description of error, if applicable

Status Codes

Example

Request URL

https://{baseURI}/location/{uuid}

Request

POST https://{baseURI}/location/{uuid}
Content-Type: application/json
Authorization: Bearer {access-token}
{
  "uuid": "uuid",
  "dropOffDateTime": "2018-06-08T09:00:45-0600",
  "dropOffLocation": {
    "latitude": 47.610378,
    "longitude": -122.200676,
    "name": "Bellevue",
    "address": {
      "streetAddress": "601 108th Ave NE",
      "addressCountry": "US",
      "addressLocality": "Bellevue",
      "addressRegion": "WA",
      "postalCode": "98004"
    }
  }
}

Response Header

Date: Mon, 11 Jun 2018 17:43:28 GMT
Server: pproxy/d8b665e
Content-Length: 170     
Content-Type: application/json
concur-correlationid: {concur-correlationid}

Response Body

{ 
  "concur-correlationId": "concur-correlationId",
  "requestId": "requestId",  
  "appVersion": "appVersion",                    
  "message": "Event Received"                          
 }                       

Schema

See the schema documentation below for the specifications of each type, plus the various schemas that are shared components of each receipt schema.

The user locations API includes users and itineraries (locations) in addition to information about the company and post type (add or cancel).

Property Name Type Format Description
uuid String - Required UUID of the user.
dropOffDateTime String DateTime Required Date Time where the user was dropped off (in RFC3339 format)
dropOffLocation Object JSON Required Location where the user was dropped off

dropOffLocation

Property Name Type Format Description
name String - Canonical name of the location.
latitude Number Float Required Numeric value of latitude (Range -90.00 and 90.00)
longitude Number Float Required Numeric value of longitude (Range -180.00 and 180.00)
address Object JSON Address where the user was dropped off

address

Property Name Type Format Description
streetAddress String - Street address of the location.
addressLocality String - Canonical City name of the address
addressRegion String - 1 to 3 character country subdivision code as defined in ISO 3166-2:2013
addressCountry String - 2 or 3 character country code as defined in ISO 3166-1:2013
postalCode String - Postal code of the address

errorDescription

Property Name Type Format Description
fieldName Array - Errors associated with the given fieldName

RECEIPTS

Receipts v4 - Get Started

Overview

The Receipts V4 API accepts three different formulae for posting a receipt:

  1. Receipt Data - Your receipt data is stored along with an automatically generated receipt image file.
  2. Receipt Data & Receipt Image - Your receipt data and receipt image file are stored.
  3. Receipt Image w/o Data - Your receipt image file is stored along with some accompanying metadata.

All of the above are receipt resources, but the service draws a distinction between resources with data versus resources that are standalone images.

Resources with data are schema-enforced and are referred to as e-receipts.

Resources of standalone images are referred to as Image-Only Receipts.

These two different resources are sent/fetched from the Receipts V4 API via different endpoints: * E-Receipts (Receipts With Data) - Use E-Receipt Endpoints * Image-Only Receipts (Standalone Images Without Data) - Use Image-Only Receipt Endpoints

Note: The Receipts V4 API only provides GET access to individual or user’s receipts that have been submitted through this API, and, therefore the response will not be comprehensive of every user receipt within SAP Concur. All other images should be obtained via the Image v1 API. Additionally, only the receipts will be returned, there will not be any corresponding entry data. Examples of Enterprise apps that should use the Image v1 API include: ERP integrations for financial journal entry postings, VAT reclaim integrations that obtain transactions to calculate VAT reclaim, project billing integrations used to substantiate expenses billed back, etc.

Important Usage Restrictions

SAP Concur systems and clients rely on e-receipts to be legally valid tax documents in the relevant government jurisdictions. Use of the Receipts endpoint to post e-receipts must therefore meet the following criteria:

Overview of Version 4.0

Version 4.0 of the Receipts API offers features like more receipt types, automatic e-receipt generation in end user’s preferred language and ability for partners to provide detailed tax information. Unlike version 3.0, we are discontinuing the use of matching facts; instead the partner will have to create a receipt for a specific end user. Receipts 4.0 works only with the new Authentication API.

Explore the API

Prerequisites

Read the Getting Started section of Authentication API.

Once you have registered your application, read about the API endpoints, or click the button to download a request collection for Postman.

Run in Postman

Retrieve a User Access Token:

Before making requests to the Receipts API, you must obtain an access token from the Authentication API.

The response will include an access_token field, which contains your access token. For subsequent calls, you will need to include this access token in the Authorization header of your calls. An id_token will be also included in the response. In order to retrieve the unique ID for your user, you will have to decode this id_token at jwt.io. You will need this ID in order to post receipts.

Examples:

cURL:

curl -d "client_secret={YOUR SECRET}&client_id={YOUR CLIENT ID}&grant_type=password&username={YOUR USERNAME}&password={YOUR PASSWORD}" https://us.api.concursolutions.com/oauth2/v0/token

HTTPie:

http -f POST https://us.api.concursolutions.com/oauth2/v0/token client_secret={YOUR SECRET} client_id={YOUR CLIENT ID} grant_type=password username={YOUR USERNAME} password=P{YOUR PASSWORD}

Explore the API in JavaScript

Below are some simple NodeJS code snippets for getting a token and posting a receipt.

Retrieve a User Access Token:

'use strict';
const request = require('request');

request.post({
    url:'https://us.api.concursolutions.com/oauth2/v0/token',
    form: {
        client_secret: 'YOUR VALUE HERE',
        client_id: 'YOUR VALUE HERE',
        username: 'YOUR VALUE HERE',
        password: 'YOUR VALUE HERE',
        grant_type: 'password'
    }},
    (err, httpResponse, body) => {
        if(err) { console.log(err); }
        console.log('Status:', httpResponse.statusCode);
        console.log('Response:', body);
    });

Post a Receipt

'use strict';
const https = require('https');

const ACCESS_TOKEN = 'YOUR ACCESS TOKEN HERE';
const USER_ID = 'YOUR VALUE HERE';
const receipt = JSON.stringify(YOUR_RECEIPT_HERE);

const options = {
    hostname: 'us.api.concursolutions.com',
    path: `/receipts/v4/users/${USER_ID}`,
    method: 'POST',
    headers: {
        'Authorization': `Bearer ${ACCESS_TOKEN}`,
        'Content-Type': 'application/json',
        'Content-Length': Buffer.byteLength(receipt),
        'Link': '<http://schema.concursolutions.com/general-receipt.schema.json>;rel=describedBy'
    }
};

const req = https.request(options, (res) => {
    console.log('statusCode:', res.statusCode);
    console.log('headers:', res.headers);

    res.on('data', (data) => {
        process.stdout.write(data);
    });
});

req.write(receipt);
req.end();

req.on('error', (e) => {
    console.error(e);
});

Endpoints

Definitions of Resources

Note: The Receipts V4 API only provides GET access to individual or user’s receipts that have been submitted through this API, and, therefore the response will not be comprehensive of every user receipt within SAP Concur. All other images should be obtained via the Image v1 API. Additionally, only the receipts will be returned, there will not be any corresponding entry data. Examples of Enterprise apps that should use the Image v1 API include: ERP integrations for financial journal entry postings, VAT reclaim integrations that obtain transactions to calculate VAT reclaim, project billing integrations used to substantiate expenses billed back, etc.

Supported Image Formats

General

Endpoint Response Format Request Summary
GET / JSON Get service index URLs
GET /v4/status/:receiptId JSON Get the status of a receipt

Endpoint: Service Index

GET /

Making a GET request to the root of the service will return a list of current endpoints. If endpoint URLs ever change, the service index will be updated. To ensure that you are using the correct URLs, the safest practice is to check the service index before every request. The response will include current URLs for all endpoints in the receipt service.

Example Requests:

cURL:

curl -H "Authorization: Bearer {YOUR ACCESS TOKEN}" https://us.api.concursolutions.com/receipts/

HTTPie:

http https://us.api.concursolutions.com/receipts/ 'Authorization:Bearer {YOUR ACCESS TOKEN}'

Example Response:

{
  "links": [
    {
      "rel": "self",
      "href": "https://us.api.concursolutions.com/receipts/v4"
    },
    {
      "rel": "receipt-get",
      "method": "GET",
      "href": "https://us.api.concursolutions.com/receipts/v4/{receiptId}"
    },
    {
      "rel": "receipt-post",
      "method": "POST",
      "href": "https://us.api.concursolutions.com/receipts/v4/users/{userId}"
    },
    {
      "rel": "receipts-get-user",
      "method": "GET",
      "href": "https://us.api.concursolutions.com/receipts/v4/users/{userId}"
    },
    {
      "rel": "schemas-get",
      "method": "GET",
      "href": "https://us.api.concursolutions.com/receipts/schemas"
    }
  ]
}

Back to Top

E-Receipts

Endpoint Response Format Request Summary
GET /schemas JSON Get currently supported receipt schemas
POST /v4/users/:userId N/A Post a receipt
GET /v4/users/:userId JSON Get a user's receipts
GET /v4/:receiptId JSON Get a receipt by ID
GET /v4/:receiptId/image image file Get a receipt image.

Endpoint: Schemas

GET /schemas/:schemaId
Parameter Requirement Value
schemaId optional The ID of the schema to be returned.

The response to a GET request to /schemas will have a list of JSON validation schemas for available receipt types. An array of supportingSchemas is also returned, but these do not represent actual receipt types.

If a schema ID is provided, then only the schema with that ID will be returned, instead of the entire schema index. The ID's of schemas are not UUIDs, but are instead just the names of the schema with the extension .schema.json. For example, car-rental-receipt.schema.json or air-receipt.schema.json.

One of the receipt schemas must be included in the link header of receipt POST requests with the relationship of describedBy. This looks like link: <http://schema.concursolutions.com/{RECEIPT TYPE}.schema.json>;rel=describedBy.

Example Requests:

cURL for the schema index:

curl -H "Authorization: Bearer {YOUR ACCESS TOKEN}" https://us.api.concursolutions.com/receipts/schemas/

HTTPie for the schema index:

http https://us.api.concursolutions.com/receipts/schemas 'Authorization:Bearer {YOUR ACCESS TOKEN}'

cURL for a single schema:

curl -H "Authorization: Bearer {YOUR ACCESS TOKEN}" https://us.api.concursolutions.com/receipts/schemas/car-rental-receipt.schema.json

HTTPie for a single schema:

http https://us.api.concursolutions.com/receipts/schemas/car-rental-receipt.schema.json 'Authorization:Bearer {YOUR ACCESS TOKEN}'

Example Response:

{
  "receiptSchemas": [
    {
      "rel": "http://schema.concursolutions.com/air-receipt.schema.json",
      "method": "GET",
      "href": "https://us.api.concursolutions.com/receipts/schemas/air-receipt.schema.json"
    },
    {
      "rel": "http://schema.concursolutions.com/car-rental-receipt.schema.json",
      "method": "GET",
      "href": "https://us.api.concursolutions.com/receipts/schemas/car-rental-receipt.schema.json"
    },
    {
      "rel": "http://schema.concursolutions.com/general-receipt.schema.json",
      "method": "GET",
      "href": "https://us.api.concursolutions.com/receipts/schemas/general-receipt.schema.json"
    },
    {
      "rel": "http://schema.concursolutions.com/ground-transport-receipt.schema.json",
      "method": "GET",
      "href": "https://us.api.concursolutions.com/receipts/schemas/ground-transport-receipt.schema.json"
    },
    {
      "rel": "http://schema.concursolutions.com/hotel-receipt.schema.json",
      "method": "GET",
      "href": "https://us.api.concursolutions.com/receipts/schemas/hotel-receipt.schema.json"
    },
    {
      "rel": "http://schema.concursolutions.com/jpt-ic-card-receipt.schema.json",
      "method": "GET",
      "href": "https://us.api.concursolutions.com/receipts/schemas/jpt-ic-card-receipt.schema.json"
    },
    {
      "rel": "http://schema.concursolutions.com/rail-receipt.schema.json",
      "method": "GET",
      "href": "https://us.api.concursolutions.com/receipts/schemas/rail-receipt.schema.json"
    }
  ],
  "supportingSchemas": [
    {
      "rel": "http://schema.concursolutions.com/address-original.schema.json",
      "method": "GET",
      "href": "https://us.api.concursolutions.com/receipts/schemas/address-original.schema.json"
    },
    {
      "rel": "http://schema.concursolutions.com/address.schema.json",
      "method": "GET",
      "href": "https://us.api.concursolutions.com/receipts/schemas/address.schema.json"
    },
    {
      "rel": "http://schema.concursolutions.com/common.schema.json",
      "method": "GET",
      "href": "https://us.api.concursolutions.com/receipts/schemas/common.schema.json"
    },
    {
      "rel": "http://schema.concursolutions.com/discount.schema.json",
      "method": "GET",
      "href": "https://us.api.concursolutions.com/receipts/schemas/discount.schema.json"
    },
    {
      "rel": "http://schema.concursolutions.com/line-item.schema.json",
      "method": "GET",
      "href": "https://us.api.concursolutions.com/receipts/schemas/line-item.schema.json"
    },
    {
      "rel": "http://schema.concursolutions.com/location.schema.json",
      "method": "GET",
      "href": "https://us.api.concursolutions.com/receipts/schemas/location.schema.json"
    },
    {
      "rel": "http://schema.concursolutions.com/merchant.schema.json",
      "method": "GET",
      "href": "https://us.api.concursolutions.com/receipts/schemas/merchant.schema.json"
    },
    {
      "rel": "http://schema.concursolutions.com/payments.schema.json",
      "method": "GET",
      "href": "https://us.api.concursolutions.com/receipts/schemas/payments.schema.json"
    },
    {
      "rel": "http://schema.concursolutions.com/receipt-core.schema.json",
      "method": "GET",
      "href": "https://us.api.concursolutions.com/receipts/schemas/receipt-core.schema.json"
    },
    {
      "rel": "http://schema.concursolutions.com/taxes.schema.json",
      "method": "GET",
      "href": "https://us.api.concursolutions.com/receipts/schemas/taxes.schema.json"
    }
  ]
}

Back to Top

Endpoint: Get Receipt Status

GET /v4/status/:receiptId
Parameter Requirement Value
receiptId required The id of the receipt associated with the image.

This endpoint may be used to see the current processing status of a receipt.

When a successful POST request is made the Link header of the response contains a 'processing-status' URL. This processing-status URL will be available for two weeks after the initial POST and will provide information regarding the processing status of your receipt.

There are four possible top level statuses: ACCEPTED, FAILED, PROCESSING, and PROCESSED.

In additional to a high level status, information will be provided in an array of event logs. Events that may be included in the logs will be typed as INFO, DEBUG, WARNING, or ERROR.

Example event messages:

Type Message
INFO Receipt accepted. Queued for processing.
INFO Initiated receipt processing. (event for each attempt)
ERROR Error from User Profile service. Queued for reprocessing.
ERROR Error from Imaging service. Queued for reprocessing.
ERROR Error during image generation or retrieval. Queued for reprocessing.
INFO Receipt image generated.
ERROR Processing failed.
INFO Processing finished.

Example Requests:

cURL:

curl -H "Authorization: Bearer {YOUR ACCESS TOKEN}" https://us.api.concursolutions.com/receipts/v4/status/{RECEIPT ID}

HTTPie:

http https://us.api.concursolutions.com/receipts/v4/status/{RECEIPT ID} "Authorization: Bearer {YOUR ACCESS TOKEN}"

Example Response:

{
  "status": "PROCESSED",
  "logs": [
    {
      "logLevel": "INFO",
      "message": "Receipt accepted. Queued for processing.",
      "timestamp": "Mon, 08 May 2017 23:05:52 GMT"
    },
    {
      "logLevel": "INFO",
      "message": "Initiated receipt processing.",
      "timestamp": "Mon, 08 May 2017 23:05:52 GMT"
    },
    {
      "logLevel": "INFO",
      "message": "Receipt image generated.",
      "timestamp": "Mon, 08 May 2017 23:05:53 GMT"
    },
    {
      "logLevel": "INFO",
      "message": "Processing finished.",
      "timestamp": "Mon, 08 May 2017 23:05:54 GMT"
    }
  ]
}

Back to Top

Endpoint: Post a Receipt

POST /v4/users/:userId
Parameter Requirement Value
userId required The id of the user to whom the receipt belongs.
receipt required The JSON receipt to be posted.
image optional Image of the receipt. If an image isn't provided, one will be generated automatically from the JSON. Refer to Supported Image Formats for more information.

Creating a receipt requires JSON data about the transaction and, optionally, an image of the receipt. If an image is not supplied with the request, SAP Concur will automatically generate a receipt image based on the data provided. JSON schemas are used to validate the format of receipt data received in POST requests.

SAP Concur systems and clients rely on e-receipts to be legally valid tax documents in the relevant government jurisdictions. Please see this information regarding important usage restrictions.

Successful POST requests will receive a response of 201 Created. The Location header of the response contains a URL for your receipt. Once the receipt has been processed, it can be retrieved at this URL. The Link header of the response contains a processing-status URL for your receipt. More information can be found here.

Helpful Notes: - Include link as a header and make its value: “;rel=describedBy” - Copy a sample receipt of that receipt type from the documentation (https://developer.concur.com/api-reference/receipts/sample-receipts.html) and post it into the body of this POST call → you can then edit this body to your specification

If you are not providing an image with your receipt data, the body of the request should be your receipt JSON.

Receipt images may be posted along with data. In this case, SAP Concur will use the provided image instead of generating a new one. To post data and an image, use multipart form data. The Content-Type:multipart/form-data header must be set. The image should be included under the key image, and the receipt JSON should be included under the key receipt. For information regarding image size, dimension, and type, please refer to Supported Image Formats.

Example Requests:

cURL data without image:

curl -v -X POST https://us.api.concursolutions.com/receipts/v4/users/{USER ID FROM YOUR ID TOKEN} \
-H "Authorization: Bearer {YOUR ACCESS TOKEN}" \
-H "Content-Type: application/json" \
-H "link: <http://schema.concursolutions.com/{VALIDATION SCHEMA FROM SCHEMA ENDPOINT}.schema.json>;rel=describedBy" \
-d @{PATH TO YOUR RECEIPT JSON}

cURL data and image:

curl -v -k -X POST https://us.api.concursolutions.com/receipts/v4/users/{USER ID FROM YOUR ID TOKEN} \
-H "Authorization: Bearer {YOUR ACCESS TOKEN}" \
-H "Content-Type:multipart/form-data" \
-H "link: <http://schema.concursolutions.com/{VALIDATION SCHEMA FROM SCHEMA ENDPOINT}.schema.json>;rel=describedBy" \
-F "receipt=<{PATH TO YOUR RECEIPT JSON};type=application/json" \
-F "image=@{PATH TO YOUR IMAGE};type={FILE MIME TYPE OF YOUR IMAGE}"

HTTPie data without image:

http POST https://us.api.concursolutions.com/receipts/v4/users/{USER ID FROM YOUR ID TOKEN} \
"Authorization:Bearer {YOUR ACCESS TOKEN}" \
"Content-Type: application/json" \
"link: <http://schema.concursolutions.com/{VALIDATION SCHEMA FROM SCHEMA ENDPOINT}.schema.json>;rel=describedBy" \
< {PATH TO YOUR RECEIPT JSON}

Example Response:

HTTP/1.1 201 Created
Link: <http://schema.concursolutions.com/car-rental-receipt.schema.json>; rel="describedBy", <https://us.api.concursolutions.com/receipts/v4/status/b0a4ab2bce8a49a08cf177cb997bf2ee>; rel="processing-status"
Location: https://us.api.concursolutions.com/receipts/v4/b0a4ab2bce8a49a08cf177cb997bf2ee
Content-Length: 0
Connection: keep-alive

Back to Top

Endpoint: Get a Receipt by ID

GET /v4/:receiptId
Parameter Requirement Value
receiptId required The id of the receipt to be returned.

Returns the JSON receipt associated with the ID in the URL.

Example Requests:

cURL:

curl -H "Authorization: Bearer {YOUR ACCESS TOKEN}" https://us.api.concursolutions.com/receipts/v4/{RECEIPT ID}

HTTPie:

http https://us.api.concursolutions.com/receipts/v4/{RECEIPT ID} "Authorization: Bearer {YOUR ACCESS TOKEN}"

Example Response

{
  "dateTimeReceived": "2016-09-28T21:41:21.087Z",
  "id": "85b76a2bf51a4ed7b8b252994d7d9e2b",
  "image": "",
  "receipt": {
    ...Receipt JSON...
  },
  "userId": "08bdda1e-0d4f-4261-9f1b-f9b8d9f817d6",
  "validationSchema": "http://schema.concursolutions.com/car-rental-receipt.schema.json",
  "self": "https://us.api.concursolutions.com/receipts/v4/85b76a2bf51a4ed7b8b252994d7d9e2b",
  "template": "https://us.api.concursolutions.com/receipts/v4/{receiptId}"
}

Back to Top

Endpoint: Get Receipts By UserId

GET /v4/users/:userId
Parameter Requirement Value
userId required The id of the user whose receipts will be returned.

Returns all receipts for a given user ID.

Example Requests:

cURL:

curl -H "Authorization: Bearer {YOUR ACCESS TOKEN}" https://us.api.concursolutions.com/receipts/v4/users/{USER ID}

HTTPie:

http https://us.api.concursolutions.com/receipts/v4/users/{USER ID} "Authorization: Bearer {YOUR ACCESS TOKEN}"

Example Response:

{
  "receipts": [
    {
      "dateTimeReceived": "2016-09-28T21:41:21.087Z",
      "id": "85b76a2bf51a4ed7b8b252994d7d9e2b",
      "image": "",
      "receipt": {
        ...Receipt JSON...
      },
      "userId": "08bdda1e-0d4f-4261-9f1b-f9b8d9f817d6",
      "validationSchema": "http://schema.concursolutions.com/car-rental-receipt.schema.json",
      "self": "https://us.api.concursolutions.com/receipts/v4/85b76a2bf51a4ed7b8b252994d7d9e2b",
      "template": "https://us.api.concursolutions.com/receipts/v4/{receiptId}"
    },
    {
      "dateTimeReceived": "2016-09-28T19:59:30.488Z",
      "id": "df8c1161d917439c9e6f141fd0d6b588",
      "image": "",
      "receipt": {
        ...Receipt JSON...
      },
      "userId": "08bdda1e-0d4f-4261-9f1b-f9b8d9f817d6",
      "validationSchema": "http://schema.concursolutions.com/car-rental-receipt.schema.json",
      "self": "https://us.api.concursolutions.com/receipts/v4/df8c1161d917439c9e6f141fd0d6b588",
      "template": "https://us.api.concursolutions.com/receipts/v4/{receiptId}"
    },
    ...
  ]
}

Back to Top

Endpoint: Get Receipt Image

GET /v4/:receiptId/image
Parameter Requirement Value
receiptId required The id of the receipt associated with the image.

If an image or PDF document was generated by or POSTed to Receipts v4, this endpoint can return the image in the same format that it was originally received by the API. Images for receipts created with v3 of the API are not accessible via this endpoint.

Example Requests:

cURL:

curl -H "Authorization: Bearer {YOUR ACCESS TOKEN}" https://us.api.concursolutions.com/receipts/v4/{RECEIPT ID}/image

HTTPie:

http https://us.api.concursolutions.com/receipts/v4/{RECEIPT ID}/image "Authorization: Bearer {YOUR ACCESS TOKEN}"

Back to Top

Image-Only Receipts

Note: This API is not designed to obtain the receipt images attached to an expense report. If you are an Enterprise Partner creating integrations that are intended to obtain final-approved Expense or Invoice data, and the accompanying receipt images that substantiate those transactions you will need to use Image v1. These scenarios include, but are not limited to: ERP integrations for financial journal entry postings, VAT reclaim integrations that obtain transactions to calculate VAT reclaim, project billing integrations used to substantiate expenses billed back, etc.

Endpoint Response Format Request Summary
POST /v4/users/:userId/image-only-receipts N/A Post an image-only receipt
GET /v4/users/:userId/image-only-receipts JSON Get a user's image-only receipts
GET /v4/image-only-receipts/:receiptId JSON Get an image-only receipt by ID

Endpoint: Post an Image-Only Receipt

POST /v4/users/:userId/image-only-receipts
Parameter Requirement Value
userId required The id of the user to whom the receipt image belongs.
image required Image of the receipt. Refer to Supported Image Formats for more information.

Successful POST requests will receive a response of 202 Accepted. The Location header of the response contains a URL for your receipt image. Once the receipt has been processed, it can be retrieved at this URL. The Link header of the response contains a processing-status URL for your receipt image.

Helpful Notes: - The header must include content-type with multipart/form-data as its value - In the body, add "image" as a key and select "file" from the dropdown since you will be linking an image file. Then, choose your saved image file as the value.

For information regarding image size, dimension, and type, please refer to Supported Image Formats.

Example Requests:

cURL:

curl -v -X POST https://us.api.concursolutions.com/receipts/v4/users/{USER ID FROM YOUR ID TOKEN}/image-only-receipts \
-H "Authorization: Bearer {YOUR ACCESS TOKEN}" \
-H "Content-Type:multipart/form-data" \
-F "image=@{PATH TO YOUR IMAGE};type=image/{FILE MIME TYPE OF YOUR IMAGE}"

Example Response:

HTTP/1.1 202 Accepted
Link: <https://us.api.concursolutions.com/receipts/v4/status/b0a4ab2bce8a49a08cf177cb997bf2ee>; rel="processing-status"
Location: https://us.api.concursolutions.com/receipts/v4/images/b0a4ab2bce8a49a08cf177cb997bf2ee
Content-Length: 0
Connection: keep-alive

Back to Top

Endpoint: Get Image-Only Receipts By UserId

GET /v4/users/:userId/image-only-receipts
Parameter Requirement Value
userId required The id of the user whose receipt images will be returned.

Returns the JSON metadata of receipt images for the user ID specified in the URL. Results should be paginated in the same manner as the e-receipt endpoint.

Example Requests:

cURL:

curl -H "Authorization: Bearer {YOUR ACCESS TOKEN}" https://us.api.concursolutions.com/receipts/v4/users/{USER ID}/image-only-receipts

HTTPie:

http https://us.api.concursolutions.com/receipts/v4/users/{USER ID}/image-only-receipts "Authorization: Bearer {YOUR ACCESS TOKEN}"

Example Response:

HTTP/1.1 200 OK
Content-Length: 800
Connection: keep-alive

{
    "receiptsImages": [
        {
            "dateTimeReceived": "Wed May 24 2017 16:14:17 GMT+00:00",
            "id": "a90fc48e0f0a44f2bd4838fd773b07a5",
            "image": "https://us.api.concursolutions.com/receipts/v4/image-only-receipts/a90fc48e0f0a44f2bd4838fd773b07a5/image",
            "userId": "abcd123456efg"
        },
        { ... },
    ],
    "next": "https://us.api.concursolutions.com/receipts/v4/users/abcd123456efg/image-only-receipts/page/1507587575592_d4721b2f3b304a9a9325fabdad5f50ad"
}

Back to Top

Endpoint: Get an Image-Only Receipt by ID

GET /v4/image-only-receipts/:receiptId
Parameter Requirement Value
receiptId required The id of the receipt image to be returned.

Returns the JSON metadata associated with the ID in the URL.

Example Requests:

cURL:

curl -v -X GET https://us.api.concursolutions.com/receipts/v4/image-only-receipts/{RECEIPT ID} \
-H "Authorization: Bearer {YOUR ACCESS TOKEN}"

HTTPie:

http https://us.api.concursolutions.com/receipts/v4/image-only-receipts/{RECEIPT ID} "Authorization: Bearer {YOUR ACCESS TOKEN}"

Example Response

HTTP/1.1 200 OK
Content-Length: 272
Connection: keep-alive

{
    "dateTimeReceived": "Wed May 24 2017 16:14:17 GMT+00:00",
    "id": "a90fc48e0f0a44f2bd4838fd773b07a5",
    "image": "https://us.api.concursolutions.com/receipts/v4/image-only-receipts/a90fc48e0f0a44f2bd4838fd773b07a5/image",
    "userId": "abcd123456efg"
}

Back to Top

Endpoint: Get Receipt Image (Image-Only)

GET /v4/image-only-receipts/:receiptId/image
Parameter Requirement Value
receiptId required The id of the receipt image to be returned.

Returns the image in the same format that it was originally received by the API (image/png, image/jpg, image/jpeg, image/tiff, image/tif, image/gif, or application/pdf).

Example Requests:

cURL:

curl -H "Authorization: Bearer {YOUR ACCESS TOKEN}" https://us.api.concursolutions.com/receipts/v4/image-only-receipts/{RECEIPT ID}/image

HTTPie:

http https://us.api.concursolutions.com/receipts/v4/image-only-receipts/{RECEIPT ID}/image "Authorization: Bearer {YOUR ACCESS TOKEN}"

Back to Top

Supported Receipt Types

Receipts can be any of the following types

See the schema documentation below for the specifications of each type, plus the various schemas that are shared components of each receipt schema. Property names mentioned in bold italics are required fields.

Schemas

Address

Property Name Type Format Description
streetAddress string N/A
addressLocality string N/A City
addressRegion string ^[a-zA-Z0-9]{1,3}$ 1 to 3 character country subdivision code as defined in ISO 3166-2:2013
addressCountry string country-code 2 or 3 character country code as defined in ISO 3166-1:2013
postalCode string N/A

Air Receipt

Schema for airline receipts. * Includes all of Receipt Core Definitions

Property Name Type Format Description
itineraryLocator string ^(?!\s*$).+ Unique ID of an itinerary (also know as a trip) in Concur’s Itinerary Service. An itinerary can contain one or more bookings from various sources.
tickets array tickets Air tickets issued.
lineItems array lineItems Ancillary airline fees.
tickets
Property Name Type Format Description
number string N/A Ticket number issued by the airline when the payment is made. Ticket numbers are globally unique for all IATA carriers. The first 3 digits identify the airline. The three digit code for each airline can be found here. For example the ticket number for American Airlines where 001 is the airline: 0012375432602.
recordLocator string N/A Confirmation identifier for the ticket created by the airline. For most airlines this is a 6 character alphanumeric code that is unique for a short period of time and could be reused in the future.
issueDateTime string date-time Date and time the ticket was issued.
pseudoCityCode string ^[a-zA-Z]{3}$ IATA city code the ticket was issued from. For example, SEA for Seattle.
IATAAgencyNumber string ^[0-9]{8}$ Identifying number assigned by the IATA to the agency issuing the ticket.
agencyName string N/A Name of the agency issuing the ticket.
passengerName string N/A Name of the passenger associated with the ticket.
coupons array coupons Flights issued within this transaction.
coupons
Property Name Type Format Description
originationAirportIATACode string ^[a-zA-Z]{3}$ IATA airport code of the flight’s origin.
originationDateTime string date-time Date and time of origin.
destinationAirportIATACode string ^[a-zA-Z]{3}$ IATA airport code of the flight’s destination.
destinationDateTime string date-time Date and time of destination.
flightNumber string N/A Flight identifier.
couponNumber string ^(?!\s*$).+ Identifier associated with the given coupon.
operatingAirlineCode string ^[a-zA-Z]{2}$ IATA code of the airline operating the flight.
marketingCarrier string ^[a-zA-Z0-9]{3,8}$ Flight designator booking the flight.
operatingCarrier string ^[a-zA-Z0-9]{3,8}$ Flight designator operating the flight.
classOfServiceCode string ^[a-zA-Z]$ Class of service per the airline’s class of service codes. Most airlines use the same codes but some airlines have custom codes.
fareBasisCode string ^[a-zA-Z0-9]{2,8}$ Rate code the airline used to calculate the fare for this flight.
ticketDesignatorCode string ^[a-zA-Z0-9*?]{1,10}$ A valid ticket designator code to indicate what type of discount is applied, such as for a child or infant, or airline employee. This is a 1 to 10 alphanumeric code and can optionally include a single asterisk. Ticket designators are free-form text codes which help identify ticket types. Airlines determine which ticket designators they will use as no standards currently exist.
fare string ^[-]?\d*.?\d+$ Fare charged for the flight.
taxes array Taxes Schema for objects that make up an array of taxes. Used in most receipt types.
lineItems array lineItems Line Items/fees specific to a leg of the trip. Eg. Baggage fees, class of service fees, priority boarding, meals.
Definitions
Property Name Type Format Description
IATAAirportCode string ^[a-zA-Z]{3}$ 3-letter IATA code for an airport.
IATAAirlineCode string ^[a-zA-Z]{2}$ 2-letter code for an airline.
IATACityCode string ^[a-zA-Z]{3}$ 3-letter IATA city code. For example, SEA for Seattle.
IATAAgencyNumber string ^[0-9]{8}$ 8-character ID number assigned by the IATA to an agency.
flightDesignator string ^[a-zA-Z0-9]{3,8}$
classOfServiceCode string ^[a-zA-Z]$
fareBasisCode string ^[a-zA-Z0-9]{2,8}$
ticketDesignatorCode string ^[a-zA-Z0-9*?]{1,10}$

Car Rental Receipt

Schema for car rentals. This does not include ride services or taxis. * Includes all of Receipt Core Definitions

Property Name Type Format Description
itineraryLocator string ^(?!\s*$).+ Unique ID of an itinerary (also know as a trip) in Concur’s Itinerary Service. An itinerary can contain one or more bookings from various sources.
segmentLocator string ^(?!\s*$).+ Unique ID of a single travel event in Concur’s Itinerary Service. An itinerary can contain one or more bookings and each booking can contain one or more segments. The segmentLocator uniquely identifies an event like a car rental with a specific start and end date or a single air segment/sector.
startDateTime string date-time A subset of ISO 8601 date-times. The first restriction is that the dateTime requires a date, a time (at least the hour portion), and a UTC offset. The second restriction is that the dateTime does not allow a time to be formatted in UTC time (2015-11-02T14:30Z - notice the Z) without an offset; this is because it would be impossible for us to know the original offset so we could not generate a receipt with the correct local time.
endDateTime string date-time A subset of ISO 8601 date-times. The first restriction is that the dateTime requires a date, a time (at least the hour portion), and a UTC offset. The second restriction is that the dateTime does not allow a time to be formatted in UTC time (2015-11-02T14:30Z - notice the Z) without an offset; this is because it would be impossible for us to know the original offset so we could not generate a receipt with the correct local time.
pickupLocation object Location Schema representing a location, including geographical information and a postal address. Used in multiple receipt types.
dropoffLocation object Location Schema representing a location, including geographical information and a postal address. Used in multiple receipt types.
rentalDays integer N/A Total number of days for which the car was rented.
rentalAgreementNumber string N/A Agreement identifier.
confirmationNumber string N/A Booking confirmation identifier.
vehicle object vehicle
driverName string N/A Name of the driver/renter of the vehicle.
distance object distance Distance traveled.
odometerReadingOut number N/A Odometer reading at the start of the rental period. A number with up to one decimal place is expected.
odometerReadingIn number N/A Odometer reading at the end of the rental period. A number with up to one decimal place is expected.
additionalDriver boolean N/A Additional approved driver (true) or not (false).
lineItems array lineItems Break down of all car rental charges. This could include daily rate, fees, insurance, GPS rental and other add-ons.
vehicle
Property Name Type Format Description
registrationNumber string N/A Registration or license plate identifier.
description string N/A Vehicle description, including year, make and model.
classReservedCode string ^[a-zA-Z]{4}$ Four-letter Association of Car Rental Industry Systems Standard (ACRISS) car code.
classRentedCode string ^[a-zA-Z]{4}$ Actual vehicle rented ACRISS identifier.
classChargedCode string ^[a-zA-Z]{4}$ Car class code actually charged to the user.
engineSize string ^[0-9]{1,4}$ Engine displacement in cubic centimeters.
Definitions
Property Name Type Format Description
acrissCarCode string ^[a-zA-Z]{4}$ Four-letter Association of Car Rental Industry Systems Standard (ACRISS) car code.
engineSize string ^[0-9]{1,4}$ Engine displacement in cubic centimeters.

Common Definitions

Shared definitions that are utilized in multiple receipt types.

Definitions
Property Name Type Format Description
dateTime string date-time The dateTime validation validates for a subset of ISO 8601 date-times. The first restriction is that the dateTime requires a date, a time (at least the hour portion), and a UTC offset. The second restriction is that the dateTime does not allow a time to be formatted in UTC time (2015-11-02T14:30Z - notice the Z) without an offset; This is because it would be impossible for us to know the original offset so we could not generate a receipt with the correct local time.
duration string ^(-)?P(?:(-?[0-9,.])Y)?(?:(-?[0-9,.])M)?(?:(-?[0-9,.])W)?(?:(-?[0-9,.])D)?(?:T(?:(-?[0-9,.])H)?(?:(-?[0-9,.])M)?(?:(-?[0-9,.]*)S)?)?$ Duration of a time interval as defined in ISO 8601
nonEmptyString string ^(?!\s*$).+ Non-empty string. Length must be at least 1 character.
addressRegion string ^[a-zA-Z0-9]{1,3}$ 1 to 3 character country subdivision code as defined in ISO 3166-2:2013
addressCountry string country-code 2 or 3 character country code as defined in ISO 3166-1:2013
currency string ^[-]?\d*.?\d+$ String representing an amount of money. Should not include a currency code or symbol, as this information is included in the currencyCode field of the receipt.
currencyCode string currency-code 3-letter currency code as defined in ISO 4217
latitude number N/A Numeric latitude value between -90 and 90
longitude number N/A Numeric longitude value between -180 and 180
positiveInteger integer N/A Positive integer value of at least 1
positiveNumber number N/A Positive number value of at least 0
negativeCurrency string ^[-]\d*.?\d+$ String representing a negative amount of money, normally used for a discount. Should not include a currency code or symbol, as this information is included in the currencyCode field of the receipt.
distance
Property Name Type Format Description
totalDistance number N/A
unit N/A N/A Can be any of the following values: mi, km

Discount

Schema for discounts, such as coupons or discount codes, that could be part of a transaction.

Property Name Type Format Description
discountName string N/A The name of the discount.
discountCode string N/A The code for the discount.
discountRate string N/A The percentage of discount provided.
discountAmount string ^[-]\d*.?\d+$ String representing a negative amount of money, normally used for a discount. Should not include a currency code or symbol, as this information is included in the currencyCode field of the receipt.

General Receipt

General receipt type for transactions that do not fall under one of the more specific receipt types. This might include retail stores or restaurants. * Includes all of Receipt Core Definitions

Property Name Type Format Description
lineItems array lineItems Line items specified for general receipts.

Ground Transport Receipt

Schema for ground transportation receipts. This includes essentially all forms of non-aerial transportation, except those that run on railed tracks. * Includes all of Receipt Core Definitions

Property Name Type Format Description
itineraryLocator string ^(?!\s*$).+ Non-empty string. Length must be at least 1 character.
segmentLocator string ^(?!\s*$).+ Non-empty string. Length must be at least 1 character.
classOfService string ^(?!\s*$).+ Non-empty string. Length must be at least 1 character.
startDateTime string date-time A subset of ISO 8601 date-times. The first restriction is that the dateTime requires a date, a time (at least the hour portion), and a UTC offset. The second restriction is that the dateTime does not allow a time to be formatted in UTC time (2015-11-02T14:30Z - notice the Z) without an offset; this is because it would be impossible for us to know the original offset so we could not generate a receipt with the correct local time.
endDateTime string date-time A subset of ISO 8601 date-times. The first restriction is that the dateTime requires a date, a time (at least the hour portion), and a UTC offset. The second restriction is that the dateTime does not allow a time to be formatted in UTC time (2015-11-02T14:30Z - notice the Z) without an offset; this is because it would be impossible for us to know the original offset so we could not generate a receipt with the correct local time.
travelDuration string ^(-)?P(?:(-?[0-9,.])Y)?(?:(-?[0-9,.])M)?(?:(-?[0-9,.])W)?(?:(-?[0-9,.])D)?(?:T(?:(-?[0-9,.])H)?(?:(-?[0-9,.])M)?(?:(-?[0-9,.]*)S)?)?$ Duration of a time interval as defined in ISO 8601
mapUrl string Google Maps URI Pattern Link to an image of the traveled route.
pickupLocation object Location Schema representing a location, including geographical information and a postal address. Used in multiple receipt types.
dropoffLocation object Location Schema representing a location, including geographical information and a postal address. Used in multiple receipt types.
distance object distance Object representing a distance.
driverNumber string N/A Unique identifier assigned by the ride company to a driver.
lineItems array lineItems Descriptive breakdown of the fare charged. For example: base fare, distance travelled, discount and other add-ons.

Google Maps URI Pattern: ^https://(www|maps).(googleapis|google).[a-z]+/maps/

Hotel Receipt

Schema for hotel receipts. * Includes all of Receipt Core Definitions

Property Name Type Format Description
itineraryLocator string ^(?!\s*$).+ Unique ID of an itinerary (also know as a trip) in Concur’s Itinerary Service. An itinerary can contain one or more bookings from various sources.
segmentLocator string ^(?!\s*$).+ Unique ID of a single travel event in Concur’s Itinerary Service. An itinerary can contain one or more bookings and each booking can contain one or more segments. The segmentLocator uniquely identifies an event like a car rental with a specific start and end date or a single air segment/sector.
property object Location Physical property location information for the hotel property. This is often different than the merchant location information.
confirmationNumber string N/A Booking identifier.
checkInDateTime string date-time A subset of ISO 8601 date-times. The first restriction is that the dateTime requires a date, a time (at least the hour portion), and a UTC offset. The second restriction is that the dateTime does not allow a time to be formatted in UTC time (2015-11-02T14:30Z - notice the Z) without an offset; this is because it would be impossible for us to know the original offset so we could not generate a receipt with the correct local time.
checkOutDateTime string date-time A subset of ISO 8601 date-times. The first restriction is that the dateTime requires a date, a time (at least the hour portion), and a UTC offset. The second restriction is that the dateTime does not allow a time to be formatted in UTC time (2015-11-02T14:30Z - notice the Z) without an offset; this is because it would be impossible for us to know the original offset so we could not generate a receipt with the correct local time.
guests array guests Guest information.
numberInParty integer N/A Number of individuals for the stay.
room object room
nightsStayed integer N/A Positive integer value of at least 1
lineItems array lineItems
guests
Property Name Type Format Description
guestNameRecord string N/A The loyalty or membership number of the hotel guest.
firstName string ^(?!\s*$).+ Non-empty string. Length must be at least 1 character.
lastName string ^(?!\s*$).+ Non-empty string. Length must be at least 1 character.
address object Address Address of the guest. It is highly recommended that the business address of the guest is provided if the hotel is provided with one. Doing so will help VAT reclamation partners who work with companies, to have compliant receipts accepted by the tax authority when filing tax reclaims.
property
Property Name Type Format Description
name string N/A The name for the location.
number string N/A The identifier the company assigned to this location.
latitude number N/A Numeric latitude value between -90 and 90
longitude number N/A Numeric longitude value between -180 and 180
internetAddress string N/A
emailAddress string N/A
telephoneNumber string N/A
faxNumber string N/A
address object Address Common address object used by all receipt types except for the JPT IC Card receipt, which uses Address-Original.
room
Property Name Type Format Description
roomNumber string N/A Room number where the guest stayed.
roomType string N/A Type of room where the guest stayed. For example, Standard, Deluxe, etc.
ratePlanType string N/A Name of the rate plan according to which the guest was charged.
averageDailyRoomRate string ^[-]?\d*.?\d+$ Average of the daily room rates for the duration of the guests stay. Room rates usually differ from day to day.
segments
Property Name Type Format Description
sequenceNumber integer N/A Unique transaction identifier for every trip taken using the IC card.
dateTime string date-time A subset of ISO 8601 date-times. The first restriction is that the dateTime requires a date, a time (at least the hour portion), and a UTC offset. The second restriction is that the dateTime does not allow a time to be formatted in UTC time (2015-11-02T14:30Z - notice the Z) without an offset; this is because it would be impossible for us to know the original offset so we could not generate a receipt with the correct local time.
fromStationCode string N/A Departure station code of the route. This code is specified to the IC Card vendor. Concur Expense has a transcoding table to Expense location codes.
fromStationName string N/A Departure station label of the route.
toStationCode string N/A Arrival station code of the route. This code is specified to the IC Card vendor. Concur Expense has a transcoding table to Expense location codes.
toStationName string N/A Arrival station label of the route.
fromIsCommuterPass boolean N/A Whether or not the departure route is included in the commuter pass subscription of the employee.
toIsCommuterPass boolean N/A Whether or not the arrival route is included in the commuter pass subscription of the employee.
distance number N/A Positive number value of at least value as 0
icCardSegment
Property Name Type Format Description
sequenceNumber integer N/A Unique transaction identifier for every trip taken using the IC card.
dateTime string date-time Transaction date and time.
fromStationCode string N/A Departure station code of the route. This code is specified to the IC Card vendor. Concur Expense has a transcoding table to Expense location codes.
fromStationName string N/A Departure station label of the route.
toStationCode string N/A Arrival station code of the route. This code is specified to the IC Card vendor. Concur Expense has a transcoding table to Expense location codes.
toStationName string N/A Arrival station label of the route.
fromIsCommuterPass boolean N/A Whether or not the departure route is included in the commuter pass subscription of the employee.
toIsCommuterPass boolean N/A Whether or not the arrival route is included in the commuter pass subscription of the employee.
distance number N/A Positive number value of at least value as 0

Line Item

Generic line item. These objects are included in arrays in most receipt types.

Property Name Type Format Description
sequenceNumber integer N/A The order in which the item appears in the sequence of line items when the receipt is rendered by Concur.
dateTime string date-time A subset of ISO 8601 date-times. The first restriction is that the dateTime requires a date, a time (at least the hour portion), and a UTC offset. The second restriction is that the dateTime does not allow a time to be formatted in UTC time (2015-11-02T14:30Z - notice the Z) without an offset; this is because it would be impossible for us to know the original offset so we could not generate a receipt with the correct local time.
reference string N/A The item SKU, identifier or some other attribute the merchant uses to reference the item.
description string ^(?!\s*$).+ Non-empty string. Length must be at least 1 character.
additionalDescription string N/A
semanticsCode string ^(?!\s*$).+ The Concur semantics code for the line item.
unitCost string ^[-]?\d*.?\d+$ Amount per unit.
quantity integer N/A
total string ^[-]?\d*.?\d+$ String representing an amount of money. Should not include a currency code or symbol, as this information is included in the currencyCode field of the receipt.
subtotal string ^[-]?\d*.?\d+$ String representing an amount of money. Should not include a currency code or symbol, as this information is included in the currencyCode field of the receipt.
taxesTotal string ^[-]?\d*.?\d+$ String representing an amount of money. Should not include a currency code or symbol, as this information is included in the currencyCode field of the receipt.
taxes array Taxes Schema for objects that make up an array of taxes. Used in most receipt types.
vatApplicable boolean N/A If the line item was subject to a value added tax then true, if not then false.
amountIncludesVat boolean N/A
discounts array discounts The discounts offered for this line item.

Location

Schema representing a location, including geographical information and a postal address. Used in multiple receipt types.

Property Name Type Format Description
name string N/A The name for the location.
number string N/A The identifier the company assigned to this location.
latitude number N/A Numeric latitude value between -90 and 90
longitude number N/A Numeric longitude value between -180 and 180
internetAddress string N/A
emailAddress string N/A
telephoneNumber string N/A
faxNumber string N/A
address object Address Common address object used by all receipt types except for the JPT IC Card receipt, which uses Address-Original.

Merchant

Schema for an object representing a merchant. The broker and seller properties in all receipts use this schema.

Property Name Type Format Description
name string ^(?!\s*$).+ Non-empty string. Length must be at least 1 character.
description string N/A Description of the service provided by the merchant.
taxId string N/A The tax identification number assigned to the merchant by the national tax authority. If the partner is providing a tax invoice, then providing a tax identification number is recommended.
location object Location Schema representing a location, including geographical information and a postal address. Used in multiple receipt types.

Payments

The payments array allows for one or more payment methods used in the transaction to be defined. All payment methods defined within the array result in the value for total in the base object of the receipt. The JSON keyword ‘anyOf’ indicates at least one of the following is required and multiple can be present: cash, creditCard, companyPaid, digitalWallet and / or unusedTicket.

cash
Property Name Type Format Description
amount string ^[-]?\d*.?\d+$ String representing an amount of money. Should not include a currency code or symbol, as this information is included in the currencyCode field of the receipt.
creditCard
Property Name Type Format Description
amount string ^[-]?\d*.?\d+$ String representing an amount of money. Should not include a currency code or symbol, as this information is included in the currencyCode field of the receipt.
cardDetail object cardDetail Credit card information.
cardDetail
Property Name Type Format Description
cardType N/A N/A Can be any of the following values: American Express, Diners Club, Discover, MasterCard, Visa, Carte Blanche, Enroute, Universal Air Travel, JCB, EuroCard
creditCardId string ^[0-9]{4}$ Last four digits of the credit card number to meet FACTA and PCI requirements
authorizationCode string N/A Authorization code for transaction.
companyPaid
Property Name Type Format Description
source N/A N/A Can be any of the following values: GhostCard, LodgeCard, DirectPay, Invoice
amount string ^[-]?\d*.?\d+$ String representing an amount of money. Should not include a currency code or symbol, as this information is included in the currencyCode field of the receipt.
cardDetail object cardDetail Credit card information.
cardDetail
Property Name Type Format Description
cardType N/A N/A Can be any of the following values: American Express, Diners Club, Discover, MasterCard, Visa, Carte Blanche, Enroute, Universal Air Travel, JCB, EuroCard
creditCardId string ^[0-9]{4}$ Last four digits of the credit card number to meet FACTA and PCI requirements
authorizationCode string N/A Authorization code for transaction.
digitalWallet
Property Name Type Format Description
source N/A N/A Can be any of the following values: ApplePay, AndroidPay, SamsungPay, PayPal, OlaMoney
amount string ^[-]?\d*.?\d+$ String representing an amount of money. Should not include a currency code or symbol, as this information is included in the currencyCode field of the receipt.
unusedTicket
Property Name Type Format Description
ticketNumber string ^(?!\s*$).+ Non-empty string. Length must be at least 1 character.
amount string ^[-]?\d*.?\d+$ String representing an amount of money. Should not include a currency code or symbol, as this information is included in the currencyCode field of the receipt.
cardDetail
Property Name Type Format Description
cardType N/A N/A Can be any of the following values: American Express, Diners Club, Discover, MasterCard, Visa, Carte Blanche, Enroute, Universal Air Travel, JCB, EuroCard
creditCardId string ^[0-9]{4}$ Last four digits of the credit card number to meet FACTA and PCI requirements
authorizationCode string N/A Authorization code for transaction.

Rail Receipt

Schema for rail or train receipts. * Includes all of Receipt Core Definitions

Property Name Type Format Description
itineraryLocator string ^(?!\s*$).+ Unique ID of an itinerary (also know as a trip) in Concur’s Itinerary Service. An itinerary can contain one or more bookings from various sources.
lineItems array lineItems Break down of all charges which could include insurance purchased for all train tickets, paid wi-fi etc.
railTickets array railTickets
railTickets
Property Name Type Format Description
ticketNumber string N/A
recordLocator string N/A Confirmation identifier for the ticket. This code is usually unique for a short period of time and could be reused by the rail company in the future.
issueDateTime string date-time Date and time the ticket was issued.
passengerName string N/A Name of the person associated withthe ticket.
fare string ^[-]?\d*.?\d+$ Fare charged for a train ticket. This will be the total of all segments in this train ticket.
segments array segments Segments for this train ticket.
segments
Property Name Type Format Description
departureStation string N/A Name of the station from which the train is departing.
departureDateTime string date-time A subset of ISO 8601 date-times. The first restriction is that the dateTime requires a date, a time (at least the hour portion), and a UTC offset. The second restriction is that the dateTime does not allow a time to be formatted in UTC time (2015-11-02T14:30Z - notice the Z) without an offset; this is because it would be impossible for us to know the original offset so we could not generate a receipt with the correct local time.
arrivalStation string N/A Name of the station where the train is arriving.
arrivalDateTime string date-time A subset of ISO 8601 date-times. The first restriction is that the dateTime requires a date, a time (at least the hour portion), and a UTC offset. The second restriction is that the dateTime does not allow a time to be formatted in UTC time (2015-11-02T14:30Z - notice the Z) without an offset; this is because it would be impossible for us to know the original offset so we could not generate a receipt with the correct local time.
trainNumber string N/A Train identifier
trainType string N/A Type of train. For example TGV or TER in France.
classOfServiceCode string ^(?!\s*$).+ The class of travel.
fare string ^[-]?\d*.?\d+$ Fare charged for this segment of the train ride.
taxes array Taxes Taxes paid for this segment.
lineItems array lineItems Line items specific to this segment. This could include meals, seat reservations, insurance etc.

Receipt Core Definitions

Core values for all receipt types. All major receipt schemas include these core objects.

Property Name Type Format Description
dateTime string date-time Date and time of the transaction.
total string ^[-]?\d*.?\d+$ The total amount of the transaction including all lineitems and taxes.
subtotal string ^[-]?\d*.?\d+$ The amount in the transaction excluding taxes.
taxesTotal string ^[-]?\d*.?\d+$ The amount of tax paid in the transaction.
discountsTotal string ^[-]\d*.?\d+$ String representing a negative amount of money, normally used for a discount. Should not include a currency code or symbol, as this information is included in the currencyCode field of the receipt.
currencyCode string currency-code Currency paid to the merchant.
broker object Merchant The entity that facilitates the transaction between the seller and end user.
seller object Merchant The entity providing service to the end user.
payments array Payments
discounts array discounts The discounts offered on this transaction.
taxes array Taxes Taxes paid as part of transaction.
reference string N/A The unique receipt provider or merchant identifier for this receipt or invoice. This value can also be referred to as transaction number, check number, order ID or similar.
collectionReference string N/A Use this key to group related receipts into a collection for credits, tips or other adjustments to the original transaction and looking at groups of receipts for analysis purposes. The reference and collectionReference keys typically have separate and unique values but could be the same for the first receipt in a collection.
taxInvoice boolean N/A A tax invoice (true) or otherwise (false).
broker
Property Name Type Format Description
name string ^(?!\s*$).+ Non-empty string. Length must be at least 1 character.
description string N/A Description of the service provided by the merchant.
taxId string N/A The tax identification number assigned to the merchant by the national tax authority. If the partner is providing a tax invoice, then providing a tax identification number is recommended.
location object Location Schema representing a location, including geographical information and a postal address. Used in multiple receipt types.
seller
Property Name Type Format Description
name string ^(?!\s*$).+ Non-empty string. Length must be at least 1 character.
description string N/A Description of the service provided by the merchant.
taxId string N/A The tax identification number assigned to the merchant by the national tax authority. If the partner is providing a tax invoice, then providing a tax identification number is recommended.
location object Location Schema representing a location, including geographical information and a postal address. Used in multiple receipt types.

Taxes

Schema for objects that make up an array of taxes. Used in most receipt types.

Property Name Type Format Description
authority object authority The country or subdivision that charged the tax as per ISO 3166-2:2013.
name string N/A
rate number N/A
rateType string N/A The rate type for the tax charged. For value added tax this could be Zero, Standard, Reduced, etc.
amount string ^[-]?\d*.?\d+$ String representing an amount of money. Should not include a currency code or symbol, as this information is included in the currencyCode field of the receipt.
authority
Property Name Type Format Description
addressCountry string country-code 2 or 3 character country code as defined in ISO 3166-1:2013
addressRegion string ^[a-zA-Z0-9]{1,3}$ 1 to 3 character country subdivision code as defined in ISO 3166-2:2013

Sample Receipts

Below we have sample receipt data and the corresponding receipt images for the following receipt types:

Air (Multiple Tickets)

Receipt Data

{
    "taxInvoice": true,
    "reference": "ABCD1234",
    "dateTime": "2099-11-10T16:04:49-0700",
    "total": "1400.40",
    "taxesTotal": "123.38",
    "subtotal": "1277.02",
    "currencyCode": "USD",
    "broker": {
        "name": "ACME Corporation",
        "description": "",
        "taxId": "123-21213",
        "location": {
            "name": "Headquarters",
            "number": "",
            "latitude": 41.8819,
            "longitude": -87.6278,
            "internetAddress": "http://www.acmecorporation.com",
            "emailAddress": "info@acmecorporation.com",
            "telephoneNumber": "1-877-555-5555",
            "faxNumber": "",
            "address": {
                "streetAddress": "333 108th Ave NE",
                "addressLocality": "Bellevue",
                "addressRegion": "WA",
                "addressCountry": "US",
                "postalCode": "98004"
            }
        }
    },
    "seller": {
        "name": "ACME Airlines",
        "description": "",
        "taxId": "867-53090",
        "location": {
            "name": "Headquarters",
            "number": "",
            "latitude": 37.2714,
            "longitude": -85.3262,
            "internetAddress": "http://www.acmeairlines.com",
            "emailAddress": "contact@acmeairlines.com",
            "telephoneNumber": "1-888-555-5555",
            "faxNumber": "",
            "address": {
                "streetAddress": "1 Ground Transport Way",
                "addressLocality": "Seattle",
                "addressRegion": "WA",
                "addressCountry": "US",
                "postalCode": "90001"
            }
        }
    },
    "taxes": [
        {
            "authority": {
                "addressCountry": "US",
                "addressRegion": "WA"
            },
            "name": "Transportation Tax",
            "rate": 7.50,
            "amount": "91.38"
        },
        {
            "authority": {
                "addressCountry": "US"
            },
            "name": "United States - Flight Segment Tax",
            "rate": 10.0,
            "amount": "32.00"
        }
    ],
    "payments": [
        {
            "amount": "1400.40",
            "cardDetail": {
                "cardType": "Visa",
                "creditCardId": "7423",
                "authorizationCode": "AB123654789"
            }
        }
    ],
    "itineraryLocator": "1122337694093",
    "tickets": [
        {
            "number": "0062698215636",
            "recordLocator": "CU9GEF",
            "issueDateTime": "2015-11-29T19:15:55-0700",
            "pseudoCityCode": "SEA",
            "IATAAgencyNumber": "87654321",
            "agencyName": "ACME Airlines",
            "passengerName": "Jimmy Dean",
            "fare": "609.31",
            "coupons": [
                {
                    "originationAirportIATACode": "SEA",
                    "originationDateTime": "2015-12-25T09:00:00-0700",
                    "destinationAirportIATACode": "MSP",
                    "destinationDateTime": "2015-12-25T14:14:00-0500",
                    "flightNumber": "DL 1768",
                    "couponNumber": "D167693",
                    "operatingAirlineCode": "DL",
                    "marketingCarrier": "DL1768",
                    "operatingCarrier": "DL1768",
                    "classOfServiceCode": "T",
                    "fareBasisCode": "YHRT15",
                    "ticketDesignatorCode": "FSG*SFR",
                    "fare": "152.33",
                    "taxes": [
                        {
                            "authority": {
                                "addressCountry": "US"
                            },
                            "name": "Transportation Tax",
                            "rate": 7.50,
                            "amount": "11.42"
                        }
                    ],
                    "lineItems": [
                        {
                            "sequenceNumber": 1,
                            "description": "United States - September 11th Security Fee",
                            "additionalDescription": "Passenger Civil Aviation Security Service Fee",
                            "semanticsCode": "OTHER",
                            "dateTime": "2015-11-29T19:15:55-0700",
                            "total": "2.80"
                        },
                        {
                            "sequenceNumber": 2,
                            "description": "United States - Passenger Facility Charge",
                            "additionalDescription": "",
                            "semanticsCode": "SEGFEE_AS_FEE",
                            "dateTime": "2015-11-29T19:15:55-0700",
                            "total": "4.50"
                        },
                        {
                            "sequenceNumber": 3,
                            "description": "United States - Flight Segment Tax",
                            "additionalDescription": "",
                            "semanticsCode": "SEGFEE_AS_TAX",
                            "dateTime": "2015-11-29T19:15:55-0700",
                            "total": "4.00"
                        }
                    ]
                },
                {
                    "originationAirportIATACode": "MSP",
                    "originationDateTime": "2015-12-25T15:25:00-0500",
                    "destinationAirportIATACode": "GFK",
                    "destinationDateTime": "2015-12-25T16:50:00-0500",
                    "flightNumber": "OO 4656",
                    "couponNumber": "D187322",
                    "operatingAirlineCode": "DL",
                    "marketingCarrier": "DL1768Z",
                    "operatingCarrier": "OO4656B",
                    "classOfServiceCode": "T",
                    "fareBasisCode": "YAD1234",
                    "ticketDesignatorCode": "FSG*SFR",
                    "fare": "121.86",
                    "taxes": [
                        {
                            "authority": {
                                "addressCountry": "US"
                            },
                            "name": "Transportation Tax",
                            "rate": 7.50,
                            "amount": "9.14"
                        }
                    ],
                    "lineItems": [
                        {
                            "sequenceNumber": 1,
                            "description": "United States - September 11th Security Fee",
                            "additionalDescription": "Passenger Civil Aviation Security Service Fee",
                            "semanticsCode": "OTHER",
                            "dateTime": "2015-11-29T19:15:55-0700",
                            "total": "2.24"
                        },
                        {
                            "sequenceNumber": 2,
                            "description": "United States - Passenger Facility Charge",
                            "additionalDescription": "",
                            "semanticsCode": "SEGFEE_AS_FEE",
                            "dateTime": "2015-11-29T19:15:55-0700",
                            "total": "3.60"
                        },
                        {
                            "sequenceNumber": 3,
                            "description": "United States - Flight Segment Tax",
                            "additionalDescription": "",
                            "semanticsCode": "SEGFEE_AS_TAX",
                            "dateTime": "2015-11-29T19:15:55-0700",
                            "total": "4.00"
                        }
                    ]
                },
                {
                    "originationAirportIATACode": "GFK",
                    "originationDateTime": "2015-12-30T17:19:00-0500",
                    "destinationAirportIATACode": "MSP",
                    "destinationDateTime": "2015-12-30T18:34:00-0500",
                    "flightNumber": "OO 4656",
                    "couponNumber": "D187322",
                    "operatingAirlineCode": "DL",
                    "marketingCarrier": "DL1768Z",
                    "operatingCarrier": "OO4656B",
                    "classOfServiceCode": "T",
                    "fareBasisCode": "YAD1234",
                    "ticketDesignatorCode": "FSG*SFR",
                    "fare": "140.14",
                    "taxes": [
                        {
                            "authority": {
                                "addressCountry": "US"
                            },
                            "name": "Transportation Tax",
                            "rate": 7.50,
                            "amount": "10.51"
                        }
                    ],
                    "lineItems": [
                        {
                            "sequenceNumber": 1,
                            "description": "United States - September 11th Security Fee",
                            "additionalDescription": "Passenger Civil Aviation Security Service Fee",
                            "semanticsCode": "OTHER",
                            "dateTime": "2015-11-29T19:15:55-0700",
                            "total": "2.58"
                        },
                        {
                            "sequenceNumber": 2,
                            "description": "United States - Passenger Facility Charge",
                            "additionalDescription": "",
                            "semanticsCode": "SEGFEE_AS_FEE",
                            "dateTime": "2015-11-29T19:15:55-0700",
                            "total": "4.14"
                        },
                        {
                            "sequenceNumber": 3,
                            "description": "United States - Flight Segment Tax",
                            "additionalDescription": "",
                            "semanticsCode": "SEGFEE_AS_TAX",
                            "dateTime": "2015-11-29T19:15:55-0700",
                            "total": "4.00"
                        }
                    ]
                },
                {
                    "originationAirportIATACode": "MSP",
                    "originationDateTime": "2015-12-30T19:25:00-0500",
                    "destinationAirportIATACode": "SEA",
                    "destinationDateTime": "2015-12-30T21:15:00-0700",
                    "flightNumber": "DL 2536",
                    "couponNumber": "D187322",
                    "operatingAirlineCode": "DL",
                    "marketingCarrier": "DL2536Z",
                    "operatingCarrier": "DL2536B",
                    "classOfServiceCode": "T",
                    "fareBasisCode": "YAD1234",
                    "ticketDesignatorCode": "FSG*SFR",
                    "fare": "194.98",
                    "taxes": [
                        {
                            "authority": {
                                "addressCountry": "US"
                            },
                            "name": "Transportation Tax",
                            "rate": 7.50,
                            "amount": "14.62"
                        }
                    ],
                    "lineItems": [
                        {
                            "sequenceNumber": 1,
                            "description": "United States - September 11th Security Fee",
                            "additionalDescription": "Passenger Civil Aviation Security Service Fee",
                            "semanticsCode": "OTHER",
                            "dateTime": "2015-11-29T19:15:55-0700",
                            "total": "3.58"
                        },
                        {
                            "sequenceNumber": 2,
                            "description": "United States - Passenger Facility Charge",
                            "additionalDescription": "",
                            "semanticsCode": "SEGFEE_AS_FEE",
                            "dateTime": "2015-11-29T19:15:55-0700",
                            "total": "5.76"
                        },
                        {
                            "sequenceNumber": 3,
                            "description": "United States - Flight Segment Tax",
                            "additionalDescription": "",
                            "semanticsCode": "SEGFEE_AS_TAX",
                            "dateTime": "2015-11-29T19:15:55-0700",
                            "total": "4.00"
                        }
                    ]
                }
            ]
        },
        {
            "number": "0062698215637",
            "recordLocator": "CU9GEF",
            "issueDateTime": "2015-11-29T19:15:55-0700",
            "pseudoCityCode": "SEA",
            "IATAAgencyNumber": "87654321",
            "agencyName": "ACME Airlines",
            "passengerName": "John Smith",
            "fare": "609.31",
            "coupons": [
                {
                    "originationAirportIATACode": "SEA",
                    "originationDateTime": "2015-12-25T09:00:00-0700",
                    "destinationAirportIATACode": "MSP",
                    "destinationDateTime": "2015-12-25T14:14:00-0500",
                    "flightNumber": "DL 1768",
                    "couponNumber": "D167693",
                    "operatingAirlineCode": "DL",
                    "marketingCarrier": "DL1768",
                    "operatingCarrier": "DL1768",
                    "classOfServiceCode": "T",
                    "fareBasisCode": "YHRT15",
                    "ticketDesignatorCode": "FSG*SFR",
                    "fare": "152.33",
                    "taxes": [
                        {
                            "authority": {
                                "addressCountry": "US"
                            },
                            "name": "Transportation Tax",
                            "rate": 7.50,
                            "amount": "11.42"
                        }
                    ],
                    "lineItems": [
                        {
                            "sequenceNumber": 1,
                            "description": "United States - September 11th Security Fee",
                            "additionalDescription": "Passenger Civil Aviation Security Service Fee",
                            "semanticsCode": "OTHER",
                            "dateTime": "2015-11-29T19:15:55-0700",
                            "total": "2.80"
                        },
                        {
                            "sequenceNumber": 2,
                            "description": "United States - Passenger Facility Charge",
                            "additionalDescription": "",
                            "semanticsCode": "SEGFEE_AS_FEE",
                            "dateTime": "2015-11-29T19:15:55-0700",
                            "total": "4.50"
                        },
                        {
                            "sequenceNumber": 3,
                            "description": "United States - Flight Segment Tax",
                            "additionalDescription": "",
                            "semanticsCode": "SEGFEE_AS_TAX",
                            "dateTime": "2015-11-29T19:15:55-0700",
                            "total": "4.00"
                        }
                    ]
                },
                {
                    "originationAirportIATACode": "MSP",
                    "originationDateTime": "2015-12-25T15:25:00-0500",
                    "destinationAirportIATACode": "GFK",
                    "destinationDateTime": "2015-12-25T16:50:00-0500",
                    "flightNumber": "OO 4656",
                    "couponNumber": "D187322",
                    "operatingAirlineCode": "DL",
                    "marketingCarrier": "DL1768Z",
                    "operatingCarrier": "OO4656B",
                    "classOfServiceCode": "T",
                    "fareBasisCode": "YAD1234",
                    "ticketDesignatorCode": "FSG*SFR",
                    "fare": "121.86",
                    "taxes": [
                        {
                            "authority": {
                                "addressCountry": "US"
                            },
                            "name": "Transportation Tax",
                            "rate": 7.50,
                            "amount": "9.14"
                        }
                    ],
                    "lineItems": [
                        {
                            "sequenceNumber": 1,
                            "description": "United States - September 11th Security Fee",
                            "additionalDescription": "Passenger Civil Aviation Security Service Fee",
                            "semanticsCode": "OTHER",
                            "dateTime": "2015-11-29T19:15:55-0700",
                            "total": "2.24"
                        },
                        {
                            "sequenceNumber": 2,
                            "description": "United States - Passenger Facility Charge",
                            "additionalDescription": "",
                            "semanticsCode": "SEGFEE_AS_FEE",
                            "dateTime": "2015-11-29T19:15:55-0700",
                            "total": "3.60"
                        },
                        {
                            "sequenceNumber": 3,
                            "description": "United States - Flight Segment Tax",
                            "additionalDescription": "",
                            "semanticsCode": "SEGFEE_AS_TAX",
                            "dateTime": "2015-11-29T19:15:55-0700",
                            "total": "4.00"
                        }
                    ]
                },
                {
                    "originationAirportIATACode": "GFK",
                    "originationDateTime": "2015-12-30T17:19:00-0500",
                    "destinationAirportIATACode": "MSP",
                    "destinationDateTime": "2015-12-30T18:34:00-0500",
                    "flightNumber": "OO 4656",
                    "couponNumber": "D187322",
                    "operatingAirlineCode": "DL",
                    "marketingCarrier": "DL1768Z",
                    "operatingCarrier": "OO4656B",
                    "classOfServiceCode": "T",
                    "fareBasisCode": "YAD1234",
                    "ticketDesignatorCode": "FSG*SFR",
                    "fare": "140.14",
                    "taxes": [
                        {
                            "authority": {
                                "addressCountry": "US"
                            },
                            "name": "Transportation Tax",
                            "rate": 7.50,
                            "amount": "10.51"
                        }
                    ],
                    "lineItems": [
                        {
                            "sequenceNumber": 1,
                            "description": "United States - September 11th Security Fee",
                            "additionalDescription": "Passenger Civil Aviation Security Service Fee",
                            "semanticsCode": "OTHER",
                            "dateTime": "2015-11-29T19:15:55-0700",
                            "total": "2.58"
                        },
                        {
                            "sequenceNumber": 2,
                            "description": "United States - Passenger Facility Charge",
                            "additionalDescription": "",
                            "semanticsCode": "SEGFEE_AS_FEE",
                            "dateTime": "2015-11-29T19:15:55-0700",
                            "total": "4.14"
                        },
                        {
                            "sequenceNumber": 3,
                            "description": "United States - Flight Segment Tax",
                            "additionalDescription": "",
                            "semanticsCode": "SEGFEE_AS_TAX",
                            "dateTime": "2015-11-29T19:15:55-0700",
                            "total": "4.00"
                        }
                    ]
                },
                {
                    "originationAirportIATACode": "MSP",
                    "originationDateTime": "2015-12-30T19:25:00-0500",
                    "destinationAirportIATACode": "SEA",
                    "destinationDateTime": "2015-12-30T21:15:00-0700",
                    "flightNumber": "DL 2536",
                    "couponNumber": "D187322",
                    "operatingAirlineCode": "DL",
                    "marketingCarrier": "DL2536Z",
                    "operatingCarrier": "DL2536B",
                    "classOfServiceCode": "T",
                    "fareBasisCode": "YAD1234",
                    "ticketDesignatorCode": "FSG*SFR",
                    "fare": "194.98",
                    "taxes": [
                        {
                            "authority": {
                                "addressCountry": "US"
                            },
                            "name": "Transportation Tax",
                            "rate": 7.50,
                            "amount": "14.62"
                        }
                    ],
                    "lineItems": [
                        {
                            "sequenceNumber": 1,
                            "description": "United States - September 11th Security Fee",
                            "additionalDescription": "Passenger Civil Aviation Security Service Fee",
                            "semanticsCode": "OTHER",
                            "dateTime": "2015-11-29T19:15:55-0700",
                            "total": "3.58"
                        },
                        {
                            "sequenceNumber": 2,
                            "description": "United States - Passenger Facility Charge",
                            "additionalDescription": "",
                            "semanticsCode": "SEGFEE_AS_FEE",
                            "dateTime": "2015-11-29T19:15:55-0700",
                            "total": "5.76"
                        },
                        {
                            "sequenceNumber": 3,
                            "description": "United States - Flight Segment Tax",
                            "additionalDescription": "",
                            "semanticsCode": "SEGFEE_AS_TAX",
                            "dateTime": "2015-11-29T19:15:55-0700",
                            "total": "4.00"
                        }
                    ]
                }
            ]
        }
    ],
    "lineItems": [
        {
            "sequenceNumber": 1,
            "description": "United States - September 11th Security Fee",
            "additionalDescription": "Passenger Civil Aviation Security Service Fee",
            "semanticsCode": "OTHER",
            "dateTime": "2015-11-29T19:15:55-0700",
            "total": "22.40"
        },
        {
            "sequenceNumber": 2,
            "description": "United States - Passenger Facility Charge",
            "additionalDescription": "",
            "semanticsCode": "SEGFEE_AS_FEE",
            "dateTime": "2015-11-29T19:15:55-0700",
            "total": "36.00"
        }
    ]
}

Generated Receipt Image

A Receipt Image

Car Rental

Receipt Data

{
    "taxInvoice": true,
    "reference": "ABCD1234",
    "dateTime": "2016-09-29T15:05:00-0800",
    "total": "112.71",
    "taxesTotal": "8.27",
    "subtotal": "104.44",
    "currencyCode": "USD",
    "seller": {
        "name": "ACME Corporation",
        "description": "",
        "taxId": "123-21213",
        "location": {
            "name": "SNA Airport",
            "number": "SNA34393",
            "latitude": 47.616667,
            "longitude": -122.333333,
            "internetAddress": "https://www.acmecorporation.com",
            "emailAddress": "sna_airport@acmecorporation.com",
            "telephoneNumber": "123-456-7890",
            "faxNumber": "",
            "address": {
                "streetAddress": "1 Airport Way",
                "addressLocality": "Seattle",
                "addressRegion": "WA",
                "addressCountry": "US",
                "postalCode": "90001"
            }
        }
    },
    "taxes": [
        {
            "authority": {
                "addressCountry": "US",
                "addressRegion": "WA"
            },
            "name": "Local Sales Tax",
            "rate": 8.80,
            "amount": "8.27"
        }
    ],
    "payments": [
        {
            "amount": "112.71",
            "cardDetail": {
                "cardType": "American Express",
                "creditCardId": "1009",
                "authorizationCode": "AB987654321"
            }
        }
    ],
    "startDateTime": "2014-11-05T15:05:00-0800",
    "endDateTime": "2014-11-07T15:05:00-0800",
    "rentalDays": 2,
    "discounts": [{
        "discountCode": "NO-IRS",
        "discountName": "The Family of the King shall pay less",
        "discountRate": "Per Mile"
    }
    ],
    "rentalAgreementNumber": "570344843",
    "confirmationNumber": "",
    "vehicle": {
        "registrationNumber": "",
        "description": "KIA SORENTO 2WD",
        "classReservedCode": "IDAR",
        "classRentedCode": "IDAR",
        "classChargedCode": "IDAR",
        "engineSize": "2000",
        "fuelType": "Petrol"
    },
    "distance": {
        "totalDistance": 345.6,
        "unit": "mi"
    },
    "odometerReadingOut": 31548,
    "odometerReadingIn": 31893,
    "additionalDriver": false,
    "pickupLocation": {
        "name": "House of Stark",
        "address": {
            "streetAddress": "1 Wolf Road",
            "addressLocality": "Winterfell",
            "addressCountry": "GB"
        }
    },
    "dropoffLocation": {
        "name": "The Iron Throne",
        "address": {
            "streetAddress": "42 Shadowblack Lane",
            "addressLocality": "King's Landing",
            "addressCountry": "GB"
        }
    },
    "lineItems": [
        {
            "sequenceNumber": 1,
            "reference": "",
            "description": "2 DY@ 47.00",
            "additionalDescription": "",
            "semanticsCode": "DAYS",
            "quantity": 1,
            "total": "94.00",
            "taxes": [
                {
                    "authority": {
                        "addressCountry": "US",
                        "addressRegion": "CA"
                    },
                    "name": "Local Sales Tax",
                    "rate": 8.80,
                    "amount": "8.27"
                }
            ]
        },
        {
            "sequenceNumber": 2,
            "reference": "",
            "description": "11.11% FEE",
            "additionalDescription": "",
            "semanticsCode": "AIRPORTFEE",
            "quantity": 1,
            "total": "10.44"
        }
    ]
}

Generated Receipt Image

Car Rental Receipt Image

Hotel

Receipt Data

{
    "taxInvoice": true,
    "reference": "6343430",
    "dateTime": "2016-09-29T15:05:00-0800",
    "total": "749.95",
    "subtotal": "652.67",
    "taxesTotal": "97.28",
    "currencyCode": "CAD",
    "seller": {
        "name": "ACME Corporation",
        "description": "",
        "taxId": "123-21213",
        "location": {
            "name": "ACME Hotels",
            "number": "ACME34393",
            "latitude": 47.616667,
            "longitude": -122.333333,
            "internetAddress": "https://www.acmecorporation.com",
            "emailAddress": "sna_hotel@acmecorporation.com",
            "telephoneNumber": "123-456-7890",
            "faxNumber": "",
            "address": {
                "streetAddress": "1 Hotel Way",
                "addressLocality": "Seattle",
                "addressRegion": "WA",
                "addressCountry": "US",
                "postalCode": "90001"
            }
        }
    },
    "taxes": [
        {
            "authority": {
                "addressCountry": "CA"
            },
            "name": "Hotel Room Tax",
            "rate": 11.00,
            "amount": "66.88"
        },
        {
            "authority": {
                "addressCountry": "CA"
            },
            "name": "GST",
            "rateType": "Standard",
            "rate": 5.00,
            "amount": "30.4"
        }
    ],
    "payments": [
        {
            "amount": "749.95",
            "cardDetail": {
                "cardType": "American Express",
                "creditCardId": "1002",
                "authorizationCode": "548283"
            }
        }
    ],
    "property": {
        "name": "Grand Hotel",
        "number": "",
        "latitude": 49.280011,
        "longitude": -123.117024,
        "internetAddress": "",
        "emailAddress": "",
        "telephoneNumber": "123-456-1999",
        "faxNumber": "123-456-2502",
        "address": {
            "streetAddress": "433 Hotel Street",
            "addressLocality": "Vancouver",
            "addressRegion": "BC",
            "addressCountry": "CA",
            "postalCode": "v6b 6l9"
        }
    },
    "checkInDateTime": "2016-08-25T21:11:00-0700",
    "checkOutDateTime": "2016-08-27T11:09:00-0700",
    "guests": [
        {
            "guestNameRecord": "ACME-Axxxxxxx1899",
            "firstName": "Jon",
            "lastName": "Snow",
            "address": {
                "streetAddress": "111 Black Castle",
                "addressLocality": "Toronto",
                "addressRegion": "ON",
                "addressCountry": "CA",
                "postalCode": "M2P 2B8"
            }
        }
    ],
    "numberInParty": 1,
    "room": {
        "roomNumber": "1601",
        "averageDailyRoomRate": "304.00"
    },
    "nightsStayed": 2,
    "lineItems": [
        {
            "sequenceNumber": 1,
            "dateTime": "2016-04-25T18:00:00-0700",
            "reference": "RT1601",
            "description": "Room Chrg Retail",
            "semanticsCode": "ROOMRATE",
            "quantity": 1,
            "total": "304.00",
            "taxes": [
                {
                    "authority": {
                        "addressCountry": "CA"
                    },
                    "name": "Hotel Room Tax",
                    "rate": 11.00,
                    "amount": "33.44"
                },
                {
                    "authority": {
                        "addressCountry": "CA"
                    },
                    "name": "GST",
                    "rateType": "Standard",
                    "rate": 5.00,
                    "amount": "15.20"
                }
            ]
        },
        {
            "sequenceNumber": 2,
            "dateTime": "2016-04-25T18:00:00-0700",
            "reference": "RT1601",
            "description": "Destination Marketing Fee",
            "semanticsCode": "FEE",
            "quantity": 1,
            "total": "4.56"
        },
        {
            "sequenceNumber": 3,
            "dateTime": "2016-04-26T18:00:00-0700",
            "reference": "4071",
            "description": "Hidden Bar and Lounge",
            "semanticsCode": "MINIBAR",
            "quantity": 1,
            "total": "31.55"
        },
        {
            "sequenceNumber": 4,
            "dateTime": "2016-04-26T18:00:00-0700",
            "reference": "RT1601",
            "description": "Room Chrg Retail",
            "semanticsCode": "ROOMRATE",
            "quantity": 1,
            "total": "304.00",
            "taxes": [
                {
                    "authority": {
                        "addressCountry": "CA"
                    },
                    "name": "Hotel Room Tax",
                    "rate": 11.00,
                    "amount": "33.44"
                },
                {
                    "authority": {
                        "addressCountry": "CA"
                    },
                    "name": "GST",
                    "rateType": "Standard",
                    "rate": 5.00,
                    "amount": "15.20"
                }
            ]
        },
        {
            "sequenceNumber": 5,
            "dateTime": "2016-04-26T18:00:00-0700",
            "reference": "RT1601",
            "description": "Destination Marketing Fee",
            "semanticsCode": "FEE",
            "quantity": 1,
            "total": "4.56"
        }
    ]
}

Generated Receipt Image

Hotel Receipt Image

Ground Transport

Receipt Data

{
    "taxInvoice": true,
    "reference": "ADBXTF25",
    "dateTime": "2016-09-29T15:39:46-0700",
    "total": "65.00",
    "taxesTotal": "5.69",
    "subtotal": "59.87",
    "currencyCode": "USD",
    "broker": {
        "name": "ACME Corporation",
        "taxId": "123-21213",
        "location": {
            "name": "Seattle Downtown",
            "number": "C3404",
            "latitude": 47.6097,
            "longitude": -122.3331,
            "internetAddress": "http://www.acmecorporation.com/",
            "emailAddress": "groundtransport@acmecorporation.com",
            "telephoneNumber": "206-000-0000",
            "faxNumber": "",
            "address": {
                "streetAddress": "1 Ground Transport Way",
                "addressLocality": "Seattle",
                "addressRegion": "WA",
                "addressCountry": "US",
                "postalCode": "90001"
            }
        }
    },
    "seller": {
        "name": "John Smith",
        "location": {
            "address": {
                "streetAddress": "225 42nd Ave S",
                "addressLocality": "Seattle",
                "addressRegion": "WA",
                "addressCountry": "US",
                "postalCode": "98103"
            }
        }
    },
    "taxes": [
        {
            "authority": {
                "addressCountry": "US",
                "addressRegion": "WA"
            },
            "name": "Local Sales Tax",
            "rate": 9.50,
            "amount": "5.69"
        }
    ],
    "payments": [
        {
            "amount": "65.00",
            "cardDetail": {
                "cardType": "Visa",
                "creditCardId": "4321",
                "authorizationCode": "AB123654789"
            }
        }
    ],
    "classOfService": "BLACK",
    "startDateTime": "2014-11-10T15:08:24-0500",
    "endDateTime": "2014-11-10T15:39:46-0500",
    "travelDuration": "PT21M22S",
    "pickupLocation": {
        "name": "Key Center Building, Bellevue, WA",
        "latitude": 47.4436655,
        "longitude": -122.2982266,
        "address": {
            "addressCountry": "US"
        }
    },
    "dropoffLocation": {
        "name": "Seattle-Tacoma International Airport, SeaTac, WA",
        "latitude": 47.4489,
        "longitude": -122.3094,
        "address": {
            "addressCountry": "US"
        }
    },
    "distance": {
        "totalDistance": 15.6,
        "unit": "mi"
    },
    "driverNumber": "DFE154-8567",
    "lineItems": [
        {
            "sequenceNumber": 1,
            "reference": "",
            "description": "Base Fare",
            "additionalDescription": "",
            "semanticsCode": "FEE",
            "quantity": 1,
            "total": "6.39",
            "taxes": [
                {
                    "authority": {
                        "addressCountry": "US",
                        "addressRegion": "WA"
                    },
                    "name": "Local Sales Tax",
                    "rate": 9.50,
                    "amount": "0.61"
                }
            ]
        },
        {
            "sequenceNumber": 2,
            "reference": "",
            "description": "Distance",
            "additionalDescription": "",
            "semanticsCode": "FEE",
            "quantity": 1,
            "total": "49.32",
            "taxes": [
                {
                    "authority": {
                        "addressCountry": "US",
                        "addressRegion": "WA"
                    },
                    "name": "Local Sales Tax",
                    "rate": 9.50,
                    "amount": "4.68"
                }
            ]
        },
        {
            "sequenceNumber": 3,
            "reference": "",
            "description": "Time",
            "additionalDescription": "",
            "semanticsCode": "FEE",
            "quantity": 1,
            "total": "4.16",
            "taxes": [
                {
                    "authority": {
                        "addressCountry": "US",
                        "addressRegion": "WA"
                    },
                    "name": "Local Sales Tax",
                    "rate": 9.50,
                    "amount": "0.40"
                }
            ]
        },
        {
            "sequenceNumber": 4,
            "reference": "",
            "description": "Rounding Down",
            "additionalDescription": "",
            "semanticsCode": "DISCOUNT",
            "quantity": 1,
            "total": "-0.56"
        }
    ]
}

Generated Receipt Image

Ground Transport Receipt Image

Rail (Multiple Tickets)

Receipt Data

{
    "taxInvoice": true,
    "reference": "VDFG4567",
    "dateTime": "2099-11-10T16:04:49-0700",
    "total": "394.00",
    "subtotal": "394.00",
    "taxesTotal": "0.00",
    "currencyCode": "GBP",
    "itineraryLocator": "DSFJKLT4967",
    "seller": {
        "name": "ACME Corporation",
        "description": "",
        "taxId": "321-654321",
        "location": {
            "name": "Headquarters",
            "number": "",
            "latitude": 41.8819,
            "longitude": -87.6278,
            "internetAddress": "http://www.voyages-sncf.com",
            "emailAddress": "info@uk.voyages-sncf.com",
            "telephoneNumber": "0330 822 0333",
            "address": {
                "streetAddress": "34 Tower View",
                "addressLocality": "Kings Hill, WEST MALLING",
                "addressCountry": "GB",
                "postalCode": "ME19 4ED"
            }
        }
    },
    "payments": [
        {
            "amount": "394.00",
            "cardDetail": {
                "cardType": "American Express",
                "creditCardId": "4002"
            }
        }
    ],
    "railTickets": [
        {
            "ticketNumber": "C123456",
            "recordLocator": "AZT222XFT9",
            "issueDateTime": "2015-04-30T12:37:55-0700",
            "passengerName": "John Doe",
            "fare": "197.00",
            "segments": [
                {
                    "departureStation": "Paris Est",
                    "departureDateTime": "2015-11-25T10:00:00-0700",
                    "arrivalStation": "Frankfurt Main HBF",
                    "arrivalDateTime": "2015-11-26T12:00:00+0900",
                    "trainNumber": "9557",
                    "trainType": "TGV",
                    "classOfServiceCode": "First Class",
                    "fare": "98.50"
                },
                {
                    "departureStation": "Frankfurt Main HBF",
                    "departureDateTime": "2015-11-27T10:00:00-0700",
                    "arrivalStation": "Paris Est",
                    "arrivalDateTime": "2015-11-28T12:00:00+0900",
                    "trainNumber": "9558",
                    "trainType": "TGV",
                    "classOfServiceCode": "First Class",
                    "fare": "98.50"
                }
            ]
        },
        {
            "ticketNumber": "C123457",
            "recordLocator": "AZT222XFT9",
            "issueDateTime": "2015-04-30T12:37:55-0700",
            "passengerName": "Jane Doe",
            "fare": "197.00",
            "segments": [
                {
                    "departureStation": "Paris Est",
                    "departureDateTime": "2015-11-25T10:00:00-0700",
                    "arrivalStation": "Frankfurt Main HBF",
                    "arrivalDateTime": "2015-11-26T12:00:00+0900",
                    "trainNumber": "9557",
                    "trainType": "TGV",
                    "classOfServiceCode": "First Class",
                    "fare": "98.50"
                },
                {
                    "departureStation": "Frankfurt Main HBF",
                    "departureDateTime": "2015-11-27T10:00:00-0700",
                    "arrivalStation": "Paris Est",
                    "arrivalDateTime": "2015-11-28T12:00:00+0900",
                    "trainNumber": "9558",
                    "trainType": "TGV",
                    "classOfServiceCode": "First Class",
                    "fare": "98.50"
                }
            ]
        }
    ],
    "lineItems": [
        {
            "sequenceNumber": 1,
            "semanticsCode": "FEE",
            "description": "Credit Card Fee",
            "dateTime": "2015-11-10T16:04:49-0700",
            "subtotal": "4.92",
            "total": "4.92"
        }
    ]
}

Generated Receipt Image

Rail Receipt Image

Response Codes

Success Codes

Code Message Information
200 OK Your GET request succeeded.
201 Created Your POST request succeeded. Please note that even though your request passed validation, the service still needs to create your receipt. Because of this processing time, your receipt might not be available for retrieval immediately.
202 Accepted Your request was accepted. Please note that even though your request was accepted, the service still needs to process your receipt. Because of this processing time, your receipt might not be available for retrieval immediately.

Failure Codes

Code Message Response Body Information
400 Bad Request validationErrors JSON object An error occurred while validating your post against the JSON schema. The validationErrors object will contain detailed information about what caused the validation to fail.
Request body could not be parsed This means that the body of your request was empty, or there was an error parsing it.
Link header must be provided and include a URL to a known receipt schema The link header cannot be null or empty, and must include one of the supported receipt type JSON schemas followed by ;rel=describedBy. A list of supported schemas can be retrieved from the /schemas endpoint of this service.
The specified receipt schema is not valid The schema specified in the link header was valid, but an error occurred when the service attempted to fetch the schema internally.
401 Unauthorized User ID in the URL must match the ID in the sub claim of the JWT This response occurs when the JWT used for authentication is valid, but doesn't match the correct user. When using a user JWT, the request must be to a URL for the same user that is represented in the JWT. For more information on the process of obtaining a JWT, see the Authentication service documentation.
403 Forbidden None Authentication failed for some reason. A 403 will be returned if there is no JWT in the Authorization header of the request, or if the JWT is invalid or expired. This response is also for cases where the JWT does not include the scope required to fulfill the request. For more information on JWTs and scopes, see the Authentication service documentation.
404 Not Found None The receipt(s) you requested could not be found. Check that the receipt and/or user ID that you used are correct.
413 Max file size exceeded None The image you posted exceeded the limit of 5MB.
415 Unsupported Media Type Specified Content-Type is not supported The receipt service currently supports receipt data formatted as JSON. The Content-Type header must have the value application/json or the request will fail.
Invalid image type Images must be .png, .jpg, .jpeg, .tiff, or .gif.
500 Internal Server Error Internal error This response is for generic internal server errors. Something went wrong, and we're probably already trying to fix it!
Unable to save receipt into the database An error occurred while trying to update the state of the receipt.
Could not get available receipts An error occurred while trying to fetch receipts for a user by state.

REQUEST

Request v3

This API has been deprecated.

Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.

Learn more in the API Lifecycle & Deprecation Policy.

Concur Request automates the spend request and approval process for both travel and everyday expenses, giving you the data you need to accurately track and better control spending. By increasing visibility into planned expenses and up-to-date budget data, you can make strategic spending decisions before any spending actually occurs. The Request resource provides many abilities, including viewing requests and transition of requests into the workflow.

Versions

Retrieve all requests

GET /api/v3.0/travelrequest/requests

Parameters

Name Type Format Description
offset string query Starting page offset
limit Int32 query Number of records to return (default 100)
user string query The login ID of the user who owns this Request. The user must have the Web Services Admin (Professional) or Can Administer (Standard) user role to use this parameter.
status string query The Status search term specifies which travel request or approval status to return. If no Status value is sent, the default Status of Active will be used.
modifiedAfter DateTime query This returns travel requests in which the associated dependents (header, entries, segments, allocations, attendees, comments) were modified after the specified date and time. This search term can be used along with other search terms to narrow the results. The date and time (if desired) should be in UTC. The format is: YYYY-MM-DDThh:mm:ss.
modifiedBefore DateTime query This returns travel requests in which the associated dependents (header, entries, segments, allocations, attendees, comments) were modified before the specified date and time. This search term can be used along with other search terms to narrow the results. The date and time (if desired) should be in UTC. The format is: YYYY-MM-DDThh:mm:ss.
withSegmentTypes Boolean query Pass true to populate the SegmentType field in the result.

Retrieve a request by ID

GET /api/v3.0/travelrequest/requests/{id}

Parameters

Name Type Format Description
id string path Required The Request ID
user string query The login ID of the user. Optional. The user must have the Web Services Admin (Professional) or Can Administer (Standard) user role to use this parameter.

Submit a request by ID

POST /api/v3.0/travelrequest/requests/{id}/submit

Parameters

Name Type Format Description
id string path The Request ID

Schema

Request

Name Type Format Description
AgencyOfficeName string - The travel agency office name.
AllocationFormID string - The unique identifier of the Segment Form resource (See the "Forms" resource for more information).
ApprovalLimitDate DateTime - The date by which the Request must be approved. This element appears only when integrated with Concur Travel.
ApprovalStatusCode string - The code for the approval status the Request.
ApprovalStatusName string - The approval status of the Request.
AuthorizedDate DateTime - The date the Request was authorized. Format: YYYY-MM-DDThh:mm:ss.
CashAdvances Array Cash Advance This parent element has a CashAdvance child element for each cash advance. See the CashAdvance model for the full list of child elements.
Comments Array Comment This parent element has a Comment child element for each comment. See the Comment model for the full list of child elements.
CreationDate DateTime - The date of the Request was created.
CurrencyCode string - The 3-letter ISO 4217 currency code for the Request currency. The Request currency is defined as the Request creator's default reimbursement currency.
CurrencyName string - The currency name for the Request currency. The Request currency is defined as the Request creator's default reimbursement currency.
Custom1 through Custom20 CustomField - The details from the Custom fields. These fields may not have data, depending on the configuration.
EmployeeName string - The first, middle (or middle initial), and last name of the employee who created the Request.
EndDate string - The end date of the Request.
EndTime string - The end time for the Request.
Entries Array Entry This parent element has a RequestEntry child element for each entry. See the RequestEntry model for the full list of child elements.
EverSentBack string - Indicates whether the Request has ever been sent back to the employee. Format: Y/N
Exceptions Array Exception This parent element has an Exception child element for each exception. See the Exception model for the full list of child elements.
ExtensionOf string - The ID of the initial Request that this Request is an extension of or adendum to.
HasException string - Indicates whether the Request has exceptions. Format: Y/N
HeaderFormID string - The unique identifier of the Header Form resource (See the "Forms" resource for more information).
LastModifiedDate DateTime - The date the Request was last modified. Format: YYYY-MM-DDThh:mm:ss
LoginID string - The Concur login ID of the Request owner.
Name string - The name of the Request.
PolicyID string - The unique identifier of the policy that applies to this Request. Maximum length 64 characters.
PolicyName string - The name of the policy that applies to this Request.
Purpose string - The purpose of the Request.
RequestID string - The unique key for the Request.
StartDate string - The start date of the Request.
StartTime string - The start time for the Request.
SubmitDate DateTime - The date the Request was submitted. Format: YYYY-MM-DDThh:mm:ss.
TotalApprovedAmount string - The total amount of approved expenses in the Request.
TotalPostedAmount string - The total amount of the Request.
TotalRemainingAmount string - The total amount of expenses remaining in the Request.
UserPermissions UserPermissions - The actions that the user is allowed to perform on the Request.

Cash Advance

Name Type Format Description
AmountRequested string - The amount requested in the cash advance, in the currency specified in the CurrencyCode element.
ApprovalStatusName string - The approval status of the cash advance.
Comments Array Comment This parent element has a Comment child element for each comment. Refer to the Comments model for the full list of child elements.
CurrencyCode string - The 3-letter ISO 4217 currency code for the cash advance currency.
CurrencyName string - The name of the currency for the cash advance.
EmployeeCurrencyCode string - The 3-letter ISO 4217 currency code for the employee's currency, also known as the home currency.
EmployeeCurrencyName string - The name of the employee's currency, also known as the home currency.
ExchangeRate string - The exchange rate that applies to the cash advance.
IssueDate DateTime - The issue date for the cash advance.
RequestDate DateTime - The date of cash advance request, obtained from the detailed cash advance record.
StartingBalance string - The initial balance for the cash advance.

Comment

Name Type Format Description
AuthorFirstName string - The first name of the person who made the comment.
AuthorLastName string - The last name of the person who made the comment.
CommentDateTime DateTime - The time, in GMT, when the user made the comment.
IsLatest bool - Indicates that the comment is the last one.
Value string - The text of the Request header comment.

Custom

Name Type Format Description
Code string - For list fields, this is the list item code.
ListItemID string - For list fields, this is the list item ID.
Type string - The custom field type. Possible values: Amount, Boolean, ConnectedList, Date, Integer, List, Number, Text
Value string - The value in the Org Unit or Custom field. For list fields, this is the name of the list item. Maximum length: 48 characters

Entry

Name Type Format Description
Allocations Array Allocation This parent element has an Allocation child element for each associated allocation. See the Allocation model for the full list of child elements.
ApprovedAmount string - The approved amount of the Request entry in the Request currency.
Comments Array Comment This parent element has a Comment child element for each comment. See the Comments model for the full list of child elements.
Custom1 through Custom40 CustomField - The details from the Custom fields. These fields may not have data, depending on the configuration.
EntryDescription string - The description of the Request entry.
EntryFormID string - The unique identifier of the Entry Form resource (See the "Forms" resource for more information).
Exceptions Array Exception This parent element has an Exception child element for each exception. See the Exception model for the full list of child elements.
ExchangeRate string - The exchange rate that applies to the entry.
ExpenseTypeName string - The expense type name.
ForeignAmount string - The foreign amount of the Request entry.
ForeignCurrencyCode string - The 3-letter ISO 4217 currency code for the foreign currency amount of the Request entry.
ForeignCurrencyName string - The name of the currency for the foreign amount.
LastModifiedDate DateTime - The date the entry was last modified. Format: YYYY-MM-DDThh:mm:ss
OrgUnit1 through OrgUnit6 CustomField - The details from the Org Unit custom fields. These fields may not have data, depending on the configuration.
PostedAmount string - The posted amount of the Request entry in the Request currency.
RemainingAmount string - The remaining amount of the Request entry in the Request currency.
Segments Array Segment This parent element has a Segment child element for each segment associated with the travel request. See the Segment model for the full list of child elements.
TransactionDate DateTime - The date of the Request entry.
TripType string - ['ONE_WAY' or 'ROUND_TRIP' or 'MULTI_STOP'] Trip type of the air or rail segment. Possible values are: ONE_WAY, ROUND_TRIP and MULTI_STOP.

Allocation

Name Type Format Description
Custom1 through Custom20 CustomField - The details from the Custom fields. These fields may not have data, depending on the configuration.
Percentage string - The percentage of the expense that is included in this allocation.

Exception

Name Type Format Description
Code string - The system exception code defined for the exception. Example: BADCODE
Level int - The numeric level associated with the exception. Example: 99
Message string - The user-facing message defined for the exception.

Segment

Name Type Format Description
ApprovedAmount string - The approved amount of the segment in the Request currency.
ArrivalDate string - The arrival date of the segment.
ArrivalTime string - The arrival time of the segment.
ClassOfServiceCode string - The Class of Service Code from Concur Travel. Appears only when the Request is integrated with Concur Travel.
Comments Array Comment The list of comments added for this segment.
Custom1 through Custom40 CustomField - The details from the Custom fields. These fields may not have data, depending on the configuration.
DepartureDate string - The departure date of the segment.
DepartureTime string - The departure time of the segment.
Exceptions Array Exception This parent element has an Exception child element for each exception. Refer to the Exception model for the full list of child elements.
ExchangeRate string - The exchange rate that applies to the segment.
FlightNumber string - The flight number for air segments. Appears only when Request is integrated with Concur Travel.
ForeignAmount string - The foreign currency amount of the segment.
ForeignCurrencyCode string - The 3-letter ISO 4217 currency code for the foreign currency amount of the segment.
ForeignCurrencyName string - The name of the currency for the foreign amount of the segment.
FormTypeCode string - The code for form type of the segment type.
FromLocationDetail string - The code for the starting location.
FromLocationID string - The unique identifier of the departure location. (See the "Locations" resource for more information).
FromLocationName string - The name of the starting location.
IsAgencyBooked string - Indicates whether the air segment was agency booked. Format: Y/N.
IsSelfBooked string - Indicates whether the air segment was self booked. Format: Y/N.
LastModifiedDate DateTime - The date the segment was last modified. Format: YYYY-MM-DDThh:mm:ss
OutboundSegmentID string - REQ_SEGMENT_OUTBOUND_ID
PostedAmount string - The posted amount of the segment in the Request currency.
RecordLocator string - Appears only when the Request is integrated with Concur Travel.
RemainingAmount string - The remaining amount of the segment in the Request currency.
SegmentFormID string - The unique identifier of the Segment Form resource (See the "Forms" resource for more information).
SegmentLocator string - The unique identifier for the Concur Travel segment associated with this segment. Appears only when the Request is integrated with Concur Travel.
SegmentType string - The type of itinerary segment. Format: air, car, hotel, rail, dining, event, ground, taxi, parking, other and so on
SegmentTypeCode string - The code for the type of itinerary segment.
ToLocationDetail string - The code for the ending location.
ToLocationID string - The unique identifier of the arrival location. (See the "Locations" resource for more information).
ToLocationName string - The name of the ending location.
TripLocator string - The unique identifier for the Concur Travel trip associated with this segment. Appears only when the Request is integrated with Concur Travel.

User Permissions

Name Type Format Description
Links Array Link The actions that the user is allowed to perform on the Request.
Name Type Format Description
Action string - The action that the user is allowed to perform on the resource.
Method string - The method of the request. Possible values: GET, POST, PUT and DELETE.
Url string - The URL of the resource that the user can access.

Travel Request v4 - Request Proposals Resources

Important: This API is currently in pre-release status and is only available to approved early access participants. The API is under development and might change before being generally released. To become an early access participant, contact your SAP Concur Representative.

Send proposals within a Request

Scopes

travelrequest.write - Refer to Scope Usage for full details.

HTTP Request

URI Template
POST {datacenter}/travelrequest/v4/requests/{requestUuid}/agencyproposals

Parameters

Name Type Format Description
requestUuid string - Required The unique identifier of the Request.
userId string - The unique identifier of the travel agent assigned to the travel agency linked to the proposal feature.
Required when connecting with a Company token, if empty a 400 missingRequiredParam error code will be displayed.

Payload

Agency proposals

HTTP Response

HTTP Status Codes

To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.

Payload

Agency proposals

Example

HTTP Request

POST https://us.api.concursolutions.com/travelrequest/v4/requests/{requestUuid}/agencyproposals
Accept: application/json
Authorization: Bearer {token}

HTTP Response

200 OK
{
  "agencyProposalEntries": [
    {
      "agencyProposalSegments": [
        {
          "booked": true,
          "confirmationNumber": "RecordLocator246",
          "endDate": "2021-05-02",
          "endTime": "21:18",
          "pnr": "OYY5T",
          "policyCompliantLevel": 50,
          "proposalSegmentType": "AIR",
          "startDate": "2021-05-02",
          "startTime": "20:06",
          "vendorName": "AIR FRANCE",
          "timeZone": "UTC+12:00",
          "classOfService": "Economy",
          "duration": 60,
          "flightNumber": "AF030",
          "endLocation": {
            "iataCode": "CDG"
          },
          "startLocation": {
            "iataCode": "OSL"
          }
        },
        {
           "booked" : true,
          "confirmationNumber": "RecordLocator246",
          "endDate": "2021-05-01",
          "endTime": "08:30",
          "pnr": "OYY5T",
          "policyCompliantLevel": 50,
          "proposalSegmentType": "AIR",
          "startDate": "2021-05-01",
          "startTime": "07:24",
          "vendorName": "AIR FRANCE",
          "timeZone": "UTC+12:00",
          "classOfService": "Economy",
          "duration": 60,
          "flightNumber": "AF029",
          "startLocation": {
            "iataCode": "CDG"
          },
          "endLocation": {
            "iataCode": "OSL"
          }
        }
              ],
      "transactionAmount": {
        "currency": "EUR",
        "value": 300.16
      },
      "transactionDate": "2021-03-29T03:04:05.678Z"
    },

    {
      "agencyProposalSegments": [
           {
          "booked": true,
          "comments": "Staying at Liberty Hotel",
          "confirmationNumber": "RecordLocator123",
          "endDate": "2021-05-02",
          "endTime": "10:00",
          "pnr": "OCC5T",
          "policyCompliantLevel": 50,
          "proposalSegmentType": "HOTEL",
          "startDate": "2021-05-01",
          "startTime": "18:00",
          "vendorName": "ACCOR",
          "timeZone": "UTC+12:00",
          "location": {
            "countryCode": "NO",
            "city": "Oslo"
          },
          "name": "Liberty Hotel",
          "roomDescription": "Single",
          "providerPhone": "+3260000000",
          "locationDetail": "No smoker",
          "address": "Fjord Place"
        }
      ],
      "transactionAmount": {
        "currency": "EUR",
        "value": 146.00
      },
      "transactionDate": "2021-03-29T03:04:05.678Z"
    }
  ],
  "agencyProposalType": "API",
  "approvalLimitDate": "2021-04-24T03:04:05.678Z",
  "autoSelect": false,
  "booked": true,
  "comments": "",
  "itineraryLocator": "AR15U",
  "policyCompliant": true,
  "proposalOrder": 1,
  "proposalBatchSize": 2,
  "providerMessageId": "XKRDFGE",
  "status": "PROPOSAL",
  "totalPostedAmount": {
    "currency": "EUR",
    "value": 446.16
  }
}
{
  "agencyProposalEntries": [
    {
      "agencyProposalSegments": [
        {
          "booked": true,
          "confirmationNumber": "RecordLocator246",
          "endDate": "2021-05-02",
          "endTime": "20:18",
          "pnr": "OYY5T",
          "policyCompliantLevel": 50,
          "proposalSegmentType": "AIR",
          "startDate": "2021-05-02",
          "startTime": "19:06",
          "vendorName": "AIR FRANCE",
          "timeZone": "UTC+12:00",
          "classOfService": "Economy",
          "duration": 60,
          "flightNumber": "AF031",
          "endLocation": {
            "iataCode": "CDG"
          },
          "startLocation": {
            "iataCode": "OSL"
          }
        },
        {
           "booked" : true,
          "confirmationNumber": "RecordLocator246",
          "endDate": "2021-05-01",
          "endTime": "09:30",
          "pnr": "OYY5T",
          "policyCompliantLevel": 50,
          "proposalSegmentType": "AIR",
          "startDate": "2021-05-01",
          "startTime": "08:24",
          "vendorName": "AIR FRANCE",
          "timeZone": "UTC+12:00",
          "classOfService": "Economy",
          "duration": 60,
          "flightNumber": "AF030",
          "startLocation": {
            "iataCode": "CDG"
          },
          "endLocation": {
            "iataCode": "OSL"
          }
        }
              ],
      "transactionAmount": {
        "currency": "EUR",
        "value": 350.17
      },
      "transactionDate": "2021-03-29T03:04:05.678Z"
    },

    {
      "agencyProposalSegments": [
           {
          "booked": false,
          "comments": "Staying at Opera Hotel",
          "confirmationNumber": "RecordLocator123",
          "endDate": "2021-05-02",
          "endTime": "10:00",
          "pnr": "OCC5T",
          "policyCompliantLevel": 50,
          "proposalSegmentType": "HOTEL",
          "startDate": "2021-05-01",
          "startTime": "18:00",
          "vendorName": "ACCOR",
          "timeZone": "UTC+12:00",
          "location": {
            "countryCode": "NO",
            "city": "Oslo"
          },
          "name": "Opera Hotel",
          "roomDescription": "Double",
          "providerPhone": "+3260000000",
          "locationDetail": "No smoker",
          "address": "Ulriken Place"
        }
      ],
      "transactionAmount": {
        "currency": "EUR",
        "value": 200.00
      },
      "transactionDate": "2021-03-29T03:04:05.678Z"
    }
  ],
  "agencyProposalType": "API",
  "approvalLimitDate": "2021-04-26T03:04:05.678Z",
  "autoSelect": false,
  "booked": true,
  "comments": "",
  "itineraryLocator": "AR15U",
  "policyCompliant": true,
  "proposalOrder": 2,
  "proposalBatchSize": 2,
  "providerMessageId": "XKRDFGE",
  "status": "PROPOSAL",
  "totalPostedAmount": {
    "currency": "EUR",
    "value": 550.17
  }
}

Get the list of agency proposals

Scopes

travelrequest.write - Refer to Scope Usage for full details.

HTTP Request

URI Template
GET {datacenter}/travelrequest/v4/requests/{requestUuid}/agencyproposals

Parameters

Name Type Format Description
requestUuid string - Required The unique identifier of the Request.

Payload

None.

HTTP Response

HTTP Status Codes

To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.

Payload

Agency proposals

Example

HTTP Request

GET https://us.api.concursolutions.com/travelrequest/v4/requests/{requestUuid}/agencyproposals
Accept: application/json
Authorization: Bearer {token}

HTTP Response

200 OK
[
    {
        "proposalUuid": "c76eb8f5-10fa-4840-95e0-3c730b0cad46",
        "agencyProposalEntries": [
            {
                "proposalEntryUuid": "38607d43-477b-4544-9cc3-3bcc224db838",
                "matchingExpense": {},
                "transactionDate": "2021-03-29T03:04:06.000Z",
                "comments": "Staying at Opera Hotel",
                "transactionAmount": {
                    "value": 200.00000000,
                    "currency": "EUR"
                },
                "agencyProposalSegments": [
                    {
                        "address": "Ulriken Place",
                        "booked": false,
                        "comments": "Staying at Opera Hotel",
                        "confirmationNumber": "RecordLocator123",
                        "endDate": "2021-05-02",
                        "endTime": "10:00",
                        "location": {
                            "countryCode": "NO",
                            "city": "Oslo"
                        },
                        "locationDetail": "No smoker",
                        "matchingSegmentLeg": {},
                        "name": "Opera Hotel",
                        "pnr": "OCC5T",
                        "policyCompliant": false,
                        "policyCompliantLevel": 50,
                        "proposalSegmentType": "HOTEL",
                        "proposalSegmentUuid": "ea706941-462b-4d63-a28f-9ac560adcb5e",
                        "providerPhone": "+3260000000",
                        "roomDescription": "Double",
                        "segmentTypeCode": "HOTEL",
                        "startDate": "2021-05-01",
                        "startTime": "18:00",
                        "timeZone": "UTC+12:00",
                        "vendorName": "ACCOR"
                    }
                ]
            },
            {
                "proposalEntryUuid": "654fb089-0fed-4891-ac2f-da2f480dfab4",
                "matchingExpense": {},
                "transactionDate": "2021-03-29T03:04:06.000Z",
                "comments": "",
                "transactionAmount": {
                    "value": 350.17000000,
                    "currency": "EUR"
                },
                "agencyProposalSegments": [
                    {
                        "booked": true,
                        "classOfService": "Economy",
                        "confirmationNumber": "RecordLocator246",
                        "duration": 60,
                        "endDate": "2021-05-02",
                        "endLocation": {
                            "iataCode": "CDG"
                        },
                        "endTime": "20:18",
                        "flightNumber": "AF031",
                        "matchingSegmentLeg": {},
                        "pnr": "OYY5T",
                        "policyCompliant": false,
                        "policyCompliantLevel": 50,
                        "proposalSegmentType": "AIR",
                        "proposalSegmentUuid": "e43b521a-b1b1-48a5-b368-74d36d3fc56e",
                        "segmentTypeCode": "AIRFR",
                        "startDate": "2021-05-02",
                        "startLocation": {
                            "iataCode": "OSL"
                        },
                        "startTime": "19:06",
                        "timeZone": "UTC+12:00",
                        "vendorName": "AIR FRANCE"
                    },
                    {
                        "booked": true,
                        "classOfService": "Economy",
                        "confirmationNumber": "RecordLocator246",
                        "duration": 60,
                        "endDate": "2021-05-01",
                        "endLocation": {
                            "iataCode": "OSL"
                        },
                        "endTime": "09:30",
                        "flightNumber": "AF030",
                        "matchingSegmentLeg": {},
                        "pnr": "OYY5T",
                        "policyCompliant": false,
                        "policyCompliantLevel": 50,
                        "proposalSegmentType": "AIR",
                        "proposalSegmentUuid": "f9c55ba6-bdcf-4e65-b189-40f343076784",
                        "segmentTypeCode": "AIRFR",
                        "startDate": "2021-05-01",
                        "startLocation": {
                            "iataCode": "CDG"
                        },
                        "startTime": "08:24",
                        "timeZone": "UTC+12:00",
                        "vendorName": "AIR FRANCE"
                    }
                ]
            }
        ],
        "agencyProposalType": "API",
        "approvalLimitDate": "2021-04-26T03:04:06.000Z",
        "autoSelect": false,
        "booked": true,
        "comments": "",
        "importDate": "2021-03-29T09:44:36.000Z",
        "itineraryLocator": "AR15U",
        "policyCompliant": true,
        "proposal": true,
        "proposalBatchSize": 2,
        "proposalOrder": 2,
        "providerMessageId": "XKRDFGE",
        "selected": false,
        "status": "PROPOSAL",
        "totalPostedAmount": {
            "value": 550.17000000,
            "currency": "EUR"
        }
    },
    {
        "proposalUuid": "d6de71be-3716-48cb-b133-a82e03e25bfe",
        "agencyProposalEntries": [
            {
                "proposalEntryUuid": "99a44f02-b1c3-4712-af72-77cabc6f725d",
                "matchingExpense": {
                    "id": "1ECBCB87CE27FE4AB9B5D76E20E05B98"
                },
                "transactionDate": "2021-03-29T03:04:06.000Z",
                "comments": "",
                "transactionAmount": {
                    "value": 300.16000000,
                    "currency": "EUR"
                },
                "agencyProposalSegments": [
                    {
                        "booked": true,
                        "classOfService": "Economy",
                        "confirmationNumber": "RecordLocator246",
                        "duration": 60,
                        "endDate": "2021-05-02",
                        "endLocation": {
                            "iataCode": "CDG"
                        },
                        "endTime": "21:18",
                        "flightNumber": "AF030",
                        "matchingSegmentLeg": {
                            "id": "25C97F6CD6AD9F4AB5E80D6F61730D2D"
                        },
                        "pnr": "OYY5T",
                        "policyCompliant": false,
                        "policyCompliantLevel": 50,
                        "proposalSegmentType": "AIR",
                        "proposalSegmentUuid": "7835f703-2f6b-4b71-96ef-0445355f24f8",
                        "segmentTypeCode": "AIRFR",
                        "startDate": "2021-05-02",
                        "startLocation": {
                            "iataCode": "OSL"
                        },
                        "startTime": "20:06",
                        "timeZone": "UTC+12:00",
                        "vendorName": "AIR FRANCE"
                    },
                    {
                        "booked": true,
                        "classOfService": "Economy",
                        "confirmationNumber": "RecordLocator246",
                        "duration": 60,
                        "endDate": "2021-05-01",
                        "endLocation": {
                            "iataCode": "OSL"
                        },
                        "endTime": "08:30",
                        "flightNumber": "AF029",
                        "matchingSegmentLeg": {
                            "id": "51B98284E6232A40A600E9E92710CADF"
                        },
                        "pnr": "OYY5T",
                        "policyCompliant": false,
                        "policyCompliantLevel": 50,
                        "proposalSegmentType": "AIR",
                        "proposalSegmentUuid": "9e363bdc-0ef4-4332-b5ad-98ab5b759d8f",
                        "segmentTypeCode": "AIRFR",
                        "startDate": "2021-05-01",
                        "startLocation": {
                            "iataCode": "CDG"
                        },
                        "startTime": "07:24",
                        "timeZone": "UTC+12:00",
                        "vendorName": "AIR FRANCE"
                    }
                ]
            },
            {
                "proposalEntryUuid": "b4b50e4d-4082-43ee-8a08-ccc6996fcfd3",
                "matchingExpense": {
                    "id": "CA964E3216D64746A4CFF3EFD49410C6"
                },
                "transactionDate": "2021-03-29T03:04:06.000Z",
                "comments": "Staying at Liberty Hotel",
                "transactionAmount": {
                    "value": 146.00000000,
                    "currency": "EUR"
                },
                "agencyProposalSegments": [
                    {
                        "address": "Fjord Place",
                        "booked": true,
                        "comments": "Staying at Liberty Hotel",
                        "confirmationNumber": "RecordLocator123",
                        "endDate": "2021-05-02",
                        "endTime": "10:00",
                        "location": {
                            "countryCode": "NO",
                            "city": "Oslo"
                        },
                        "locationDetail": "No smoker",
                        "matchingSegmentLeg": {
                            "id": "8D364364F706994994BA226B3356D9FE"
                        },
                        "name": "Liberty Hotel",
                        "pnr": "OCC5T",
                        "policyCompliant": false,
                        "policyCompliantLevel": 50,
                        "proposalSegmentType": "HOTEL",
                        "proposalSegmentUuid": "72ad0da9-ebe6-459b-94e0-4db1cafe173b",
                        "providerPhone": "+3260000000",
                        "roomDescription": "Single",
                        "segmentTypeCode": "HOTEL",
                        "startDate": "2021-05-01",
                        "startTime": "18:00",
                        "timeZone": "UTC+12:00",
                        "vendorName": "ACCOR"
                    }
                ]
            }
        ],
        "agencyProposalType": "API",
        "approvalLimitDate": "2021-04-24T03:04:06.000Z",
        "autoSelect": false,
        "booked": true,
        "comments": "",
        "importDate": "2021-03-29T09:44:34.000Z",
        "itineraryLocator": "AR15U",
        "policyCompliant": true,
        "proposal": true,
        "proposalBatchSize": 2,
        "proposalOrder": 1,
        "providerMessageId": "XKRDFGE",
        "selected": true,
        "status": "PROPOSAL",
        "totalPostedAmount": {
            "value": 446.16000000,
            "currency": "EUR"
        }
    }
]

Agency proposals

Name Type Format Description
agencyProposalType string - Required The agency proposal type value. Supported value: API.
importDate timestamp YYYY-MM-DDThh:mm:ss.SSS'Z Read only The date of the import.
proposalUuid string - Read only The unique identifier of one proposal for a Request.
providerMessageId string - The unique identifier of the client’s batch of proposal.
proposalBatchSize integer - Required Size of the client’s batch of proposal.
Note: If this value is greater than 1, the Request will not be sent back to the traveler as long as the expected number of proposals (respective proposalOrder) are not integrated into the Request.
proposalOrder integer - Required Sequence order of the proposal for the request.
booked boolean - Required If true, this trip is (or has to be) handled by a travel agency.
approvalLimitDate - yyyy-MM-dd'T'HH:mm:ss.SSS'Z' Limit approval date of the proposal. Past this date, the proposal will not be viable any more.
status string - Required Supported values: PROPOSAL,CONFIRMED,TICKETISSUED.
proposal boolean - Read only If true, this proposal is still in the PROPOSAL status. If false, the proposal status is CONFIRMED (tickets issued).
comments string - Free text.
itineraryLocator string - The unique identifier for Concur Travel itinerary.
autoSelect boolean - If true, the Request is approved and the confirmed proposal is sent back into the Request. Not managed yet.
selected boolean - Read only Value becomes true when that proposal is selected by the user.
totalPostedAmount object Amount The total amount for that proposal.
policyCompliant boolean - If true, the the Agency Proposal is policy compliant. Default: true
agencyProposalEntries array Agency proposal entry Minimum required: 1.

Agency proposal entry

Name Type Format Description
proposalEntryUuid string - Read only The unique identifier of one entry in a proposal for a request.
comments string - Read only Concatenate the comments of underlying segments.
transactionDate timestamp YYYY-MM-DDThh:mm:ss.SSS'Z Read only The date of the transaction in local time.
transactionAmount object Amount The amount of this entry.
exchangeRate object Exchange Rate Read only The exchange rate that applies to this entry.
agencyProposalSegment array Agency proposal segment Minimum required: 1.

Agency proposal segment

Name Type Format Description
proposalSegmentUuid string - Read only The unique identifier of one segment in a proposal for a request.
pnr string - Required The personal number of reservation.
booked boolean - Required If true, this trip is (or has to be) handled by a travel agency.
policyCompliant boolean - Read only If true, the Agency Proposal is policy compliant. true if policyComplianceLevel is 100.
policyCompliantLevel integer - A value between 0 & 100 that matches the segment compliance. 100 if fully policyCompliant, 0 if not compliant at all. Default value: 100.
comments string - Free text.
startDate date yyyy-MM-dd The date of the beginning of this segment.
startTime time yyyy-MM-dd The time of the beginning of this segment.
Required if this field set as mandator for the corresponding segment.
endDate date yyyy-MM-dd The date of the ending of this segment.
endTime time yyyy-MM-dd The time of the ending of this segment.
Required if this field set as mandator for the corresponding segment.
vendorName string - Required The vendor name for this segment.
confirmationNumber string - Required The record locator or confirmation number for the flight from the airline.
proposalSegmentType string - Required Supported values: AIR, RAIL, CAR, HOTEL, MISC
segmentTypeCode object Segment Type Required The type of the segment. Supported values: AIRFR, CARRT, HOTEL, RAILF, MISC
timeZone zoneId - The time zone of the booking.
Format:
- Fixed offsets: a fully resolved offset from UTC/Greenwich, that uses the same offset for all local date-times;
- Geographical regions: an area where a specific set of rules for finding the offset from UTC/Greenwich apply (default group is the IANA Time Zone Database (TZDB)).
agencyProposalAirSegment array Agency proposal air segment Additional fields for Air segments.
agencyProposalRailSegment array Agency proposal rail segment Additional fields for Rail segments.
agencyProposalCarSegment array Agency proposal car segment Additional fields for Car segments.
agencyProposalHotelSegment array Agency proposal hotel segment Additional fields for Hotel segments.
agencyProposalMiscSegment array Agency proposal misc segment Additional fields for Misc segments.

Agency proposal air segment

Name Type Format Description
classOfService string - Required The class of the air segment.
duration integer - Required The duration of the booked flight. Must be greater than 0.
flightNumber string - Required The flight number for the booking.
seatNumber string - The number of the seat.
aircraft string - The code of the aircraft type.
mealPreference string - The booked meal.
departureTerminal string - The departure terminal for the air segment leg.
arrivalTerminal string - The arrival terminal for the air segment leg.
startLocation object Location Required The start location of the air segment leg (Air location schema).
endLocation object Location Required The end location of the air segment leg (Air location schema).

Agency proposal rail segment

Name Type Format Description
classOfService string - Required The class of the segment leg.
duration integer - Required The duration of the booked train. Must be greater than 0.
trainNumber string - Required The train number for the booking.
wagonNumber string - The number of the wagon.
seatNumber string - The number of the seat.
startRailStation string - The code for the starting station of the segment leg.
startRailStationName string - The name of the starting station of the segment leg.
startLocation object Location Required The start location of the rail segment leg (Rail location schema).
endRailStation string - The code for the ending station of the segment leg.
endRailStationName string - The name of the ending station of the segment leg.
endLocation object Location Required The end location of the rail segment leg (Rail location schema).
mealPreference string - The booked meal.

Agency proposal car segment

Name Type Format Description
airConditioning boolean - Indicates if car has an air conditioner. Supported values: R - AC, N - No AC
carEquipment string - Any special equipment required by the renter.
classOfService string - The class of the segment leg.
transmissionPreference string - The character code that indicates if the car has auto-transmission. Supported values A - Auto, M - Manual
dropOffCollectionPhoneNumber string - The phone number for the drop-off address when the rental service offers drop-off.
endLocation object Location Required The end location of the car segment leg (city location schema).
pickupDeliveryPhoneNumber string - The phone number for the pickup address when the rental service offers pickup.
startLocation object Location Required The start location of the car segment leg (city location schema).
startLocationDetail string - Additional details about the start location.
endLocationDetail string - Additional details about the end location.

Agency proposal hotel segment

Name Type Format Description
name string - Required The hotel name for the booking.
roomDescription string - The room description for the booking. Maximum Length: 2000
providerPhone string - The phone number for the booking.
location object Location Required The location of the hotel segment leg (city location schema).
locationDetail string - Additional details about the location.
address string - The address of the booking.
postalCode string - The address postal code of the booking.

Agency proposal misc segment

Name Type Format Description
name string - Required The name for the booking.

Travel Request v4 - Request Cash Advance Resources

Note: This cash advance detail endpoint is provided within the Concur Request API for feature parity purpose only. It is highly recommended to rely only on the list of cash advances link available in the Request payload response, and not on this cash advance detail URI presented below, which will be deprecated in the future.

Get the content of an existing cash advance

Scopes

travelrequest.write - Refer to Scope Usage for full details.

HTTP Request

URI Template
GET {datacenter}/travelrequest/v4/cashadvances/{cashAdvanceUuid}

Parameters

Name Type Format Description
cashAdvanceUuid string - Required The unique identifier of the cash advance.

Payload

None.

HTTP Response

HTTP Status Codes

To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.

Payload

Cash Advance

Example

HTTP Request

GET https://us.api.concursolutions.com/travelrequest/v4/cashadvances/{cashAdvanceUuid}
Accept: application/json
Authorization: Bearer {token}

HTTP Response

200 OK
[
{
  "amountRequested": {
    "value": 1.000000,
    "currency": "USD",
    "amount": 1.000000
  },
  "approvalStatus": {
    "code": "C_PEND",
    "name": "Pending Approval"
  },
  "cashAdvanceId: EF3E237ACAA3C449B808BA75BDD049FA,
  "exchangeRate": {
    "value": 1.00000000000000,
    "operation": "MULTIPLY"
  },
  "requestDate": 2019-11-14:T10:39:00.000Z"
}
]

Travel Request v4 - Expected Expense Resources

Manage expected expenses attached to a Request.

Create a new expected expense

Scopes

travelrequest.write - Refer to Scope Usage for full details.

HTTP Request

URI Template
POST {datacenter}/travelrequest/v4/requests/{requestUuid}/expenses

Parameters

Name Type Format Description
requestUuid string - Required The unique identifier of the Request to which the expected expense is attached.
userId string - The unique identifier of the user performing the expected expense creation. Required when connecting with a Company token. If empty, a 400 missingRequiredParam error code will be displayed.

Payload

Expected Expense

HTTP Response

HTTP Status Codes

To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.

Payload

Expected Expense - The created expected expense.

Example

HTTP Request

POST https://us.api.concursolutions.com/travelrequest/v4/requests/224AF3CDCC2A5244A37C72FA5770C6F2/expenses
Content-Type: application/json
Accept: application/json
Authorization: Bearer {token}
{
  "allocations": [
    {
      "allocationAmount": {
        "currency": "USD",
        "value": 122.38
      },
      "approvedAmount": {
        "currency": "USD",
        "value": 122.38
      },
      "percentEdited": false,
      "percentage": 0,
      "postedAmount": {
        "currency": "USD",
        "value": 122.38
      },
      "systemAllocation": false
    }
  ],
  "approvedAmount": {
    "currency": "USD",
    "value": 122.38
  },
  "businessPurpose": "additional punctual trip to South of France",
  "exchangeRate": {
    "operation": "MULTIPLY",
    "value": 1
  },
  "expenseType": {
    "id": "RAILF",
    "name": "Train"
  },
  "lastComment": "",
  "location": {
    "id": "A168CDBA58AE42868961BC00278A91B3",
    "countryCode": "FR",
    "countrySubDivisionCode": "FR-75",
    "city": "Paris",
    "name": "Charles De Gaulle Intl"
  },
  "postedAmount": {
    "currency": "USD",
    "value": 122.38
  },
  "remainingAmount": {
    "currency": "USD",
    "value": 122.38
  },
  "transactionAmount": {
    "currency": "USD",
    "value": 122.38
  },
  "transactionDate": "2018-07-18T00:00:00Z",
  "tripData": {
    "agencyBooked": false,
    "legs": [
      {
        "class": {
          "code": "1ST",
          "value": "05F71FA4ED235D479C6C7039F397DA79"
        },
        "endLocation": {
          "countryCode": "FR",
          "locationCode": "FRNCE",
          "city": "Nice",
          "name": "Cote D Azur"
        },
        "returnLeg": false,
        "startDate": "2018-07-18",
        "startLocation": {
          "countryCode": "FR",
          "locationCode": "FRCDG",
          "city": "Paris",
          "name": "ROISSY"
        },
        "startTime": "21:00",
        "startLocationDetail": "none"
      }
    ],
    "segmentType": {
      "category": "REQ_SEG_RAILF",
      "code": "RAILF"
    },
    "selfBooked": false,
    "tripType": "ONE_WAY"
  }
}

HTTP Response

201 Created
{
  "href": "https://us.api.concursolutions.com/travelrequest/v4/expenses/0465224E14C23D4F8C2BC79A9D694BDD",
  "id": "0465224E14C23D4F8C2BC79A9D694BDD",
  "allocations": [
    {
      "allocationAmount": {
        "value": 122.38,
        "currency": "USD"
      },
      "approvedAmount": {
        "value": 122.38,
        "currency": "USD"
      },
      "allocationId": "28E1B1F50253CD47BE002DA7B2C218EE",
      "postedAmount": {
        "value": 122.38,
        "currency": "USD"
      },
      "expenseId": "0465224E14C23D4F8C2BC79A9D694BDD",
      "percentEdited": false,
      "systemAllocation": true,
      "percentage": 100
    }
  ],
  "approvedAmount": {
    "value": 122.38,
    "currency": "USD"
  },
  "exchangeRate": {
    "value": 1,
    "operation": "MULTIPLY"
  },
  "expenseType": {
    "id": "TRAIN",
    "name": "Train"
   },
  "postedAmount": {
    "value": 122.38,
    "currency": "USD"
  },
  "remainingAmount": {
    "value": 122.38,
    "currency": "USD"
  },
  "transactionAmount": {
    "value": 122.38,
    "currency": "USD"
  },
  "transactionDate": "2018-07-18T00:00:00.000Z",
  "tripData": {
    "agencyBooked": false,
    "selfBooked": false,
    "tripType": "ONE_WAY",
    "legs": [
      {
        "class": {
          "code": "1ST",
          "value": "05F71FA4ED235D479C6C7039F397DA79"
        },
        "endLocation": {
          "id": "CE4A6DCAC4A14D08803C28F6D5CB20F0",
          "countryCode": "FR",
          "countrySubDivisionCode": "FR-06",
          "name": "Nice",
          "locationCode": "IATA_NCE",
          "locationType": "STD"
        },
        "id": "59508E1F979B4346AC6B38677ABE6404",
        "returnLeg": false,
        "startDate": "2018-07-18",
        "startLocation": {
          "id": "A168CDBA58AE42868961BC00278A91B3",
          "countryCode": "FR",
          "countrySubDivisionCode": "FR-75",
          "name": "Paris",
          "locationCode": "IATA_CDG",
          "locationType": "STD"
        },
        "startLocationDetail": "none",
        "startTime": "21:00"
      }
    ],
    "segmentType": {
      "category": "REQ_SEG_RAILF",
      "code": "RAILF"
    }
  }
}

Get the list of expected expenses attached to a Request

Scopes

travelrequest.write - Refer to Scope Usage for full details.

HTTP Request

URI Template
GET {datacenter}/travelrequest/v4/requests/{requestUuid}/expenses

Parameters

Name Type Format Description
requestUuid string - Required The unique identifier of the Request.
userId string - The unique identifier of the user viewing the expected expenses attached to a Request. If empty when using a Company token the default system user will be assumed to perform the action.

Payload

None.

HTTP Response

HTTP Status Codes

To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.

Payload

Expected Expense - List of expected expenses attached to a Request.

operations - [RFC 5988] Pagination links to next/prev/first/last page.

Example

HTTP Request

GET https://us.api.concursolutions.com/travelrequest/v4/requests/224AF3CDCC2A5244A37C72FA5770C6F2/expenses
Accept: application/json
Authorization: Bearer {token}

HTTP Response

200 OK
[
  {
    "href": "https://us.api.concursolutions.com/travelrequest/v4/expenses/B5FB8991E390474E875D6FD5BB1FDAF1",
    "id": "B5FB8991E390474E875D6FD5BB1FDAF1",
    "allocations": [
      {
        "allocationAmount": {
          "value": 324.56,
          "currency": "USD"
        },
        "approvedAmount": {
          "value": 324.56,
          "currency": "USD"
        },
        "allocationId": "79249903DC18464AAAD61062EA383BD4",
        "postedAmount": {
          "value": 324.56,
          "currency": "USD"
        },
        "expenseId": "B5FB8991E390474E875D6FD5BB1FDAF1",
        "percentEdited": false,
        "systemAllocation": true,
        "percentage": 100
      }
    ],
    "approvedAmount": {
      "value": 324.56,
      "currency": "USD"
    },
    "exchangeRate": {
      "value": 1,
      "operation": "MULTIPLY"
    },
    "expenseType": {
      "id": "AIRFR",
      "name": "Airfare"
    },
    "postedAmount": {
      "value": 324.56,
      "currency": "USD"
    },
    "remainingAmount": {
      "value": 324.56,
      "currency": "USD"
    },
    "transactionAmount": {
      "value": 324.56,
      "currency": "USD"
    },
    "transactionDate": "2018-07-15T00:00:00.000Z",
    "tripData": {
      "agencyBooked": true,
      "selfBooked": false,
      "tripType": "ROUND_TRIP",
      "legs": [
        {
        "class": {
          "code": "1ST",
          "value": "05F71FA4ED235D479C6C7039F397DA79"
        },
          "endLocation": {
            "id": "4A33695120254EEC9261B24993DD413B",
            "countryCode": "DE",
            "countrySubDivisionCode": "DE-BE",
            "city": "Berlin",
            "iataCode": "BER",
            "name": "Berlin(Alls)"
          },
          "id": "B0F356643B38BC419AFE60E050BB79A4",
          "returnLeg": false,
          "startDate": "2018-07-15",
          "startLocation": {
            "id": "A168CDBA58AE42868961BC00278A91B3",
            "countryCode": "FR",
            "countrySubDivisionCode": "FR-75",
            "city": "Paris",
            "iataCode": "CDG",
            "name": "Charles De Gaulle Intl"
          },
          "startTime": "08:00"
        },
        {
          "endLocation": {
            "id": "A168CDBA58AE42868961BC00278A91B3",
            "countryCode": "FR",
            "countrySubDivisionCode": "FR-75",
            "city": "Paris",
            "iataCode": "CDG",
            "name": "Charles De Gaulle Intl"
          },
          "id": "345475D42A53D948A6D60181759683E8",
          "returnLeg": true,
          "startDate": "2018-07-17",
          "startLocation": {
            "id": "4A33695120254EEC9261B24993DD413B",
            "countryCode": "DE",
            "countrySubDivisionCode": "DE-BE",
            "city": "Berlin",
            "iataCode": "BER",
            "name": "Berlin(Alls)"
          },
          "startTime": "17:00"
        }
      ],
      "segmentType": {
        "category": "REQ_SEG_AIRFR",
        "code": "AIRFR"
      }
    }
  },
  {
    "href": "https://us.api.concursolutions.com/travelrequest/v4/expenses/D65BDBD5D980F6498D67A92B06A457B0",
    "id": "D65BDBD5D980F6498D67A92B06A457B0",
    "allocations": [
      {
        "allocationAmount": {
          "value": 90,
          "currency": "USD"
        },
        "approvedAmount": {
          "value": 90,
          "currency": "USD"
        },
        "allocationId": "FCAA998834A24949B01AC3C1D56AF4E3",
        "postedAmount": {
          "value": 90,
          "currency": "USD"
        },
        "expenseId": "D65BDBD5D980F6498D67A92B06A457B0",
        "percentEdited": false,
        "systemAllocation": true,
        "percentage": 100
      }
    ],
    "approvedAmount": {
      "value": 90,
      "currency": "USD"
    },
    "businessPurpose": "Airport to Office after arrival and before departure",
    "exchangeRate": {
      "value": 1,
      "operation": "MULTIPLY"
    },
    "expenseType": {
      "id": "TAXIX",
      "name": "Taxi"
    },
    "location": {
      "id": "34AB34319377456B95F5C2815CC72766",
      "countryCode": "DE",
      "countrySubDivisionCode": "DE-BER",
      "city": "Berlin, GERMANY",
      "name": "Berlin, GERMANY"
    },
    "postedAmount": {
      "value": 90,
      "currency": "USD"
    },
    "remainingAmount": {
      "value": 90,
      "currency": "USD"
    },
    "transactionAmount": {
      "value": 90,
      "currency": "USD"
    },
    "transactionDate": "2018-07-17T00:00:00.000Z"
  },
  {
    "href": "https://us.api.concursolutions.com/travelrequest/v4/expenses/C286A46A2DDF984EA28E41CEA278667D",
    "id": "C286A46A2DDF984EA28E41CEA278667D",
    "allocations": [
      {
        "allocationAmount": {
          "value": 80,
          "currency": "USD"
        },
        "approvedAmount": {
          "value": 80,
          "currency": "USD"
        },
        "allocationId": "780B3FA5B83EC24F922EBE7B5D4AED63",
        "postedAmount": {
          "value": 80,
          "currency": "USD"
        },
        "expenseId": "C286A46A2DDF984EA28E41CEA278667D",
        "percentEdited": false,
        "systemAllocation": true,
        "percentage": 100
      }
    ],
    "approvedAmount": {
      "value": 80,
      "currency": "USD"
    },
    "businessPurpose": "Estimated costs for 2 dinners in Berlin",
    "exchangeRate": {
      "value": 1,
      "operation": "MULTIPLY"
    },
    "expenseType": {
      "id": "DINNR",
      "name": "Dinner"
    },
    "location": {
      "id": "34AB34319377456B95F5C2815CC72766",
      "countryCode": "DE",
      "countrySubDivisionCode": "DE-BER",
      "city": "Berlin, GERMANY",
      "name": "Berlin, GERMANY"
    },
    "postedAmount": {
      "value": 80,
      "currency": "USD"
    },
    "remainingAmount": {
      "value": 80,
      "currency": "USD"
    },
    "transactionAmount": {
      "value": 80,
      "currency": "USD"
    },
    "transactionDate": "2018-07-17T00:00:00.000Z"
  }
]

Get the content of an expected expense

Scopes

travelrequest.write - Refer to Scope Usage for full details.

HTTP Request

URI Template
GET {datacenter}/travelrequest/v4/expenses/{expenseUuid}

Parameters

Name Type Format Description
expenseUuid string - Required The unique identifier of the expected expense.
userId string - The unique identifier of the user viewing the expected expense. If empty when using a Company token the default system user will be assumed to perform the action.

Payload

None.

HTTP Response

HTTP Status Codes

To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.

Payload

Expected Expense - The expected expense having {expenseUuid} as unique identifier.

Example 1 - for a Request segment

HTTP Request

GET https://us.api.concursolutions.com/travelrequest/v4/expenses/B5FB8991E390474E875D6FD5BB1FDAF1
Accept: application/json
Authorization: Bearer {token}

HTTP Response

200 OK
{
  "href": "https://us.api.concursolutions.com/travelrequest/v4/expenses/B5FB8991E390474E875D6FD5BB1FDAF1",
  "id": "B5FB8991E390474E875D6FD5BB1FDAF1",
  "allocations": [
    {
      "allocationAmount": {
        "value": 324.56,
        "currency": "USD"
      },
      "approvedAmount": {
        "value": 324.56,
        "currency": "USD"
      },
      "allocationId": "79249903DC18464AAAD61062EA383BD4",
      "postedAmount": {
        "value": 324.56,
        "currency": "USD"
      },
      "expenseId": "B5FB8991E390474E875D6FD5BB1FDAF1",
      "percentEdited": false,
      "systemAllocation": true,
      "percentage": 100
    }
  ],
  "approvedAmount": {
    "value": 324.56,
    "currency": "USD"
  },
  "comments": {
    "href": "https://us.api.concursolutions.com/travelrequest/v4/expenses/2F9FB5CE3AC2C74C9AC3D4AB3A83C0DA/comments",
    "id": "2F9FB5CE3AC2C74C9AC3D4AB3A83C0DA",
    "template": "http://us.api.concursolutions.com/travelrequest/v4/expenses/{id}/comments"
  },
  "exchangeRate": {
    "value": 1,
    "operation": "MULTIPLY"
  },
  "expenseType": {
    "id": "AIRFR",
    "name": "Airfare"
  },
  "parentRequest": {
    "href": "https://us.api.concursolutions.com/travelrequest/v4/request/224AF3CDCC2A5244A37C72FA5770C6F2",
    "id": "224AF3CDCC2A5244A37C72FA5770C6F2",
    "template": "http://us.api.concursolutions.com/travelrequest/v4/request/{requestUuid}"
  },
  "postedAmount": {
    "value": 324.56,
    "currency": "USD"
  },
  "remainingAmount": {
    "value": 324.56,
    "currency": "USD"
  },
  "transactionAmount": {
    "value": 324.56,
    "currency": "USD"
  },
  "transactionDate": "2018-07-15T00:00:00.000Z",
  "tripData": {
    "agencyBooked": true,
    "selfBooked": false,
    "tripType": "ROUND_TRIP",
    "legs": [
      {
        "class": {
          "code": "1ST",
          "value": "05F71FA4ED235D479C6C7039F397DA79"
        },
        "endLocation": {
          "id": "4A33695120254EEC9261B24993DD413B",
          "countryCode": "DE",
          "countrySubDivisionCode": "DE-BE",
          "city": "Berlin",
          "iataCode": "BER",
          "name": "Berlin(Alls)"
        },
        "id": "B0F356643B38BC419AFE60E050BB79A4",
        "returnLeg": false,
        "startDate": "2018-07-15",
        "startLocation": {
          "id": "A168CDBA58AE42868961BC00278A91B3",
          "countryCode": "FR",
          "countrySubDivisionCode": "FR-75",
          "city": "Paris",
          "iataCode": "CDG",
          "name": "Charles De Gaulle Intl"
        },
        "startTime": "08:00"
      },
      {
        "endLocation": {
          "id": "A168CDBA58AE42868961BC00278A91B3",
          "countryCode": "FR",
          "countrySubDivisionCode": "FR-75",
          "city": "Paris",
          "iataCode": "CDG",
          "name": "Charles De Gaulle Intl"
        },
        "id": "345475D42A53D948A6D60181759683E8",
        "returnLeg": true,
        "startDate": "2018-07-17",
        "startLocation": {
          "id": "4A33695120254EEC9261B24993DD413B",
          "countryCode": "DE",
          "countrySubDivisionCode": "DE-BE",
          "city": "Berlin",
          "iataCode": "BER",
          "name": "Berlin(Alls)"
        },
        "startTime": "17:00"
      }
    ],
    "segmentType": {
      "category": "REQ_SEG_AIRFR",
      "code": "AIRFR"
    }
  }
}

Example 2 - for a Request expected expense

HTTP Request

GET https://us.api.concursolutions.com/travelrequest/v4/expenses/C286A46A2DDF984EA28E41CEA278667D
Accept: application/json
Authorization: Bearer {token}

HTTP Response

200 OK
{
  "href": "https://us.api.concursolutions.com/travelrequest/v4/expenses/C286A46A2DDF984EA28E41CEA278667D",
  "id": "C286A46A2DDF984EA28E41CEA278667D",
  "allocations": [
    {
      "allocationAmount": {
        "value": 80,
        "currency": "USD"
      },
      "approvedAmount": {
        "value": 80,
        "currency": "USD"
      },
      "allocationId": "780B3FA5B83EC24F922EBE7B5D4AED63",
      "postedAmount": {
        "value": 80,
        "currency": "USD"
      },
      "expenseId": "C286A46A2DDF984EA28E41CEA278667D",
      "percentEdited": false,
      "systemAllocation": true,
      "percentage": 100
    }
  ],
  "approvedAmount": {
    "value": 80,
    "currency": "USD"
  },
  "businessPurpose": "Estimated costs for 2 dinners in Berlin",
  "exchangeRate": {
    "value": 1,
    "operation": "MULTIPLY"
  },
  "expenseType": {
    "id": "DINNR",
    "name": "Dinner"
  },
  "location": {
    "id": "34AB34319377456B95F5C2815CC72766",
    "countryCode": "DE",
    "countrySubDivisionCode": "DE-BER",
    "city": "Berlin, GERMANY",
    "name": "Berlin, GERMANY"
  },
  "parentRequest": {
    "href": "https://us.api.concursolutions.com/travelrequest/v4/request/224AF3CDCC2A5244A37C72FA5770C6F2",
    "id": "224AF3CDCC2A5244A37C72FA5770C6F2",
    "template": "http://us.api.concursolutions.com/travelrequest/v4/request/{requestUuid}"
  },
  "postedAmount": {
    "value": 80,
    "currency": "USD"
  },
  "remainingAmount": {
    "value": 80,
    "currency": "USD"
  },
  "transactionAmount": {
    "value": 80,
    "currency": "USD"
  },
  "transactionDate": "2018-07-17T00:00:00.000Z"
}

Update the content of an expected expense

Scopes

travelrequest.write - Refer to Scope Usage for full details.

HTTP Request

URI Template
PUT {datacenter}/travelrequest/v4/expenses/{expenseUuid}

Parameters

Name Type Format Description
expenseUuid string - Required The unique identifier of the expected expense to update.
userId string - The unique identifier of the user performing the expected expense update. Required when connecting with a Company token. If empty, a 400 missingRequiredParam error code will be displayed.

Payload

Expected Expense

HTTP Response

HTTP Status Codes

To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.

Payload

Expected Expense - The expected expense having {expenseUuid} as unique identifier after update.

Example

HTTP Request

PUT https://us.api.concursolutions.com/travelrequest/v4/expenses/B5FB8991E390474E875D6FD5BB1FDAF1
Content-Type: application/json
Accept: application/json
Authorization: Bearer {token}
{
  "id": "B5FB8991E390474E875D6FD5BB1FDAF1",
  "allocations": [
    {
      "allocationAmount": {
        "value": 432.45,
        "currency": "USD"
      },
      "approvedAmount": {
        "value": 432.45,
        "currency": "USD"
      },
      "allocationId": "79249903DC18464AAAD61062EA383BD4",
      "postedAmount": {
        "value": 432.45,
        "currency": "USD"
      },
      "expenseId": "B5FB8991E390474E875D6FD5BB1FDAF1",
      "percentEdited": false,
      "systemAllocation": true,
      "percentage": 100
    }
  ],
  "approvedAmount": {
    "value": 432.45,
    "currency": "USD"
  },
  "exchangeRate": {
    "value": 1,
    "operation": "MULTIPLY"
  },
  "expenseType": {
    "id": "AIRFR",
    "name": "Airfare"
  },
  "postedAmount": {
    "value": 432.45,
    "currency": "USD"
  },
  "remainingAmount": {
    "value": 432.45,
    "currency": "USD"
  },
  "transactionAmount": {
    "value": 432.45,
    "currency": "USD"
  },
  "transactionDate": "2018-07-16T00:00:00.000Z",
  "tripData": {
    "agencyBooked": true,
    "selfBooked": false,
    "tripType": "ROUND_TRIP",
    "legs": [
      {
        "class": {
          "code": "1ST",
          "value": "05F71FA4ED235D479C6C7039F397DA79"
        },
        "endLocation": {
          "countryCode": "DE",
          "city": "Berlin",
          "iataCode": "BER",
          "name": "Berlin(Alls)"
        },
        "id": "B0F356643B38BC419AFE60E050BB79A4",
        "returnLeg": false,
        "startDate": "2018-07-16",
        "startLocation": {
          "countryCode": "FR",
          "city": "Paris",
          "iataCode": "CDG",
          "name": "Charles De Gaulle Intl"
        },
        "startTime": "07:00"
      },
      {
        "endLocation": {
          "countryCode": "FR",
          "city": "Paris",
          "iataCode": "CDG",
          "name": "Charles De Gaulle Intl"
        },
        "id": "345475D42A53D948A6D60181759683E8",
        "returnLeg": true,
        "startDate": "2018-07-18",
        "startLocation": {
          "countryCode": "DE",
          "city": "Berlin",
          "iataCode": "BER",
          "name": "Berlin(Alls)"
        },
        "startTime": "18:00"
      }
    ],
    "segmentType": {
      "category": "REQ_SEG_AIRFR",
      "code": "AIRFR"
    }
  }
}

HTTP Response

200 OK
{
  "href": "https://us.api.concursolutions.com/travelrequest/v4/expenses/B5FB8991E390474E875D6FD5BB1FDAF1",
  "id": "B5FB8991E390474E875D6FD5BB1FDAF1",
  "allocations": [
    {
      "allocationAmount": {
        "value": 432.45,
        "currency": "USD"
      },
      "approvedAmount": {
        "value": 432.45,
        "currency": "USD"
      },
      "allocationId": "79249903DC18464AAAD61062EA383BD4",
      "postedAmount": {
        "value": 432.45,
        "currency": "USD"
      },
      "expenseId": "B5FB8991E390474E875D6FD5BB1FDAF1",
      "percentEdited": false,
      "systemAllocation": true,
      "percentage": 100
    }
  ],
  "approvedAmount": {
    "value": 432.45,
    "currency": "USD"
  },
  "exchangeRate": {
    "value": 1,
    "operation": "MULTIPLY"
  },
  "expenseType": {
    "id": "AIRFR",
    "name": "Airfare"
   },
  "parentRequest": {
    "href": "https://us.api.concursolutions.com/travelrequest/v4/request/224AF3CDCC2A5244A37C72FA5770C6F2",
    "id": "224AF3CDCC2A5244A37C72FA5770C6F2",
    "template": "http://us.api.concursolutions.com/travelrequest/v4/request/{requestUuid}"
  },
  "postedAmount": {
    "value": 432.45,
    "currency": "USD"
  },
  "remainingAmount": {
    "value": 432.45,
    "currency": "USD"
  },
  "transactionAmount": {
    "value": 432.45,
    "currency": "USD"
  },
  "transactionDate": "2018-07-16T00:00:00.000Z",
  "tripData": {
    "agencyBooked": true,
    "selfBooked": false,
    "tripType": "ROUND_TRIP",
    "legs": [
      {
        "class": {
          "code": "1ST",
          "value": "05F71FA4ED235D479C6C7039F397DA79"
        },
        "endLocation": {
          "id": "4A33695120254EEC9261B24993DD413B",
          "countryCode": "DE",
          "countrySubDivisionCode": "DE-BE",
          "city": "Berlin",
          "iataCode": "BER",
          "name": "Berlin(Alls)"
        },
        "id": "B0F356643B38BC419AFE60E050BB79A4",
        "returnLeg": false,
        "startDate": "2018-07-16",
        "startLocation": {
          "id": "A168CDBA58AE42868961BC00278A91B3",
          "countryCode": "FR",
          "countrySubDivisionCode": "FR-75",
          "city": "Paris",
          "iataCode": "CDG",
          "name": "Charles De Gaulle Intl"
        },
        "startTime": "07:00"
      },
      {
        "endLocation": {
          "id": "A168CDBA58AE42868961BC00278A91B3",
          "countryCode": "FR",
          "countrySubDivisionCode": "FR-75",
          "city": "Paris",
          "iataCode": "CDG",
          "name": "Charles De Gaulle Intl"
        },
        "id": "345475D42A53D948A6D60181759683E8",
        "returnLeg": true,
        "startDate": "2018-07-18",
        "startLocation": {
          "id": "4A33695120254EEC9261B24993DD413B",
          "countryCode": "DE",
          "countrySubDivisionCode": "DE-BE",
          "city": "Berlin",
          "iataCode": "BER",
          "name": "Berlin(Alls)"
        },
        "startTime": "18:00"
      }
    ],
    "segmentType": {
      "category": "REQ_SEG_AIRFR",
      "code": "AIRFR"
    }
  }
}

Delete an expected expense from the Request

Scopes

travelrequest.write - Refer to Scope Usage for full details.

HTTP Request

URI Template
DELETE {datacenter}/travelrequest/v4/expenses/{expenseUuid}

Parameters

Name Type Format Description
expenseUuid string - Required The unique identifier of the expected expense to delete.
userId string - The unique identifier of the user performing the deletion of the expected expense. Required when connecting with a Company token. If empty, a 400 missingRequiredParam error code will be displayed.

Payload

None.

HTTP Response

HTTP Status Codes

To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.

Payload

None.

Example

HTTP Request

DELETE https://us.api.concursolutions.com/travelrequest/v4/expenses/D65BDBD5D980F6498D67A92B06A457B0
Accept: application/json
Authorization: Bearer {token}

HTTP Response

200 OK
true

Get the list of comments for an existing expected expense

Scopes

travelrequest.write - Refer to Scope Usage for full details.

HTTP Request

URI Template
GET {datacenter}/travelrequest/v4/expenses/{expenseUuid}/comments

Parameters

Name Type Format Description
expenseUuid string - Required The unique identifier of the expected expense.
userId string - The unique identifier of the user getting the content of the comments. Required when connecting with a Company token. If empty, a 400 missingRequiredParam error code will be displayed.

Payload

None.

HTTP Response

HTTP Status Codes

To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.

Payload

Comments

Example

HTTP Request

GET https://us.api.concursolutions.com/travelrequest/v4/expenses/B5FB8991E390474E875D6FD5BB1FDAF1/comments
Accept: application/json
Authorization: Bearer {token}

HTTP Response

200 OK
[
  {
    "author": {
      "firstName": "Steve",
      "lastName": "Smith"
    },
    "creationDateTime": "2019-07-12T11:51:14.000Z",
    "isLatest": true,
    "value": "I have reviewed the required amount, too expensive. You are allowed to a maximum of 100 USD for a business meal"
  },
  {
    "author": {
      "firstName": "John",
      "lastName": "Doe"
    },
    "creationDateTime": "2019-07-12T11:11:39.000Z",
    "isLatest": false,
    "value": "Please review the required amount for approval"
  }
]

Travel Request v4 - Request Policy Resources

Get the list of existing Request policies for a given user

Scopes

travelrequest.write - Refer to Scope Usage for full details.

HTTP Request

URI Template
GET {datacenter}/travelrequest/v4/userpolicies

Parameters

Name Type Format Description
userId string - The unique identifier of the user for whom the list of Request policies will be retrieved. Required when connecting with a Company token. If empty, a 400 missingRequiredParam error.

Payload

None.

HTTP Response

HTTP Status Codes

To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.

Payload

List of Request Policies

Example

HTTP Request

GET https://us.api.concursolutions.com/travelrequest/v4/userpolicies
Accept: application/json
Authorization: Bearer {token}

HTTP Response

200 OK
[
  {
    "href": "https://us.api.concursolutions.com/travelrequest/v4/userpolicies/F4C8BD31CA9D4D6292795BE687EB9B2A",
    "id": "F4C8BD31CA9D4D6292795BE687EB9B2A",
   "name": "Internal training Request policy"
  },
  {
    "href": "https://us.api.concursolutions.com/travelrequest/v4/userpolicies/F10E6059B5A14A4C80327FE387491026",
    "id": "F10E6059B5A14A4C80327FE387491026",
   "name": "Client meeting Request policy"
  }
]

Travel Request v4 - Request Resources

Create a new Request

Scopes

travelrequest.write - Refer to Scope Usage for full details.

HTTP Request

URI Template
POST {datacenter}/travelrequest/v4/requests

Parameters

Name Type Format Description
userId string - The unique identifier of the Request owner for whom the Request will be created. The corresponding user name will be displayed in the audit trail of the Request. Required when connecting with a Company token, if empty a 400 missingRequiredParam error code will be displayed.

Payload

Request

Since this endpoint is performing a Request creation, specifying an id field in the payload is not allowed.

A newly allocated id value will be returned upon successful Request creation.

HTTP Response

HTTP Status Codes

To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.

Payload

Request - The created Request.

Example

HTTP Request

POST https://us.api.concursolutions.com/travelrequest/v4/requests
Content-Type: application/json
Accept: application/json
Authorization: Bearer {token}
{
  "businessPurpose": "Trip to Lyon for company training",
  "comment": "Company training requires to go to Lyon",
  "custom1": {
    "value": "Training part of IT Service"
  },
  "custom2": {
    "value": "8422A66A9B0142458020D9BCD4351D38"
  },
  "custom3": {
    "value": "5A0F9AF6B92E34468698040C915688BF"
  },
  "custom4": {
    "value": "3F54AE68BA66EF49A5984E5197202A4D"
  },
  "endDate": "2018-07-03",
  "endTime": "22:00",
  "startDate": "2018-07-01",
  "startTime": "07:15",
  "name": "Company Training - JULY 2018",
  "mainDestination": {
    "city": "Lyon, FRANCE",
    "countryCode": "FR",
    "countrySubDivisionCode": "FR-69",
    "name": "Lyon, FRANCE"
  },
  "policy": {
    "id": "F4C8BD31CA9D4D6292795BE687EB9B2A"
  },
  "travelAgency": {
    "id": "2EC038D7C3CBBE4ABA0914425064D34F"
  }
}

HTTP Response

201 Created
{
  "href": "https://us.api.concursolutions.com/travelrequest/v4/requests/CED5E9CD8FC1424488F9331ACF956E73",
  "id": "CED5E9CD8FC1424488F9331ACF956E73",
  "approvalStatus": {
    "code": "NOT_SUBMITTED",
    "name": "Not Submitted"
  },
  "approved": false,
  "businessPurpose": "Trip to Lyon for company training",
  "canceledPostApproval": false,
  "closed": false,
  "comment": "Company training requires to go to Lyon",
  "creationDate": "2018-05-25T08:08:59.000Z",
  "custom1": {
    "value": "Training part of IT Service"
  },
  "custom2": {
    "code": "CEN3",
    "value": "8422A66A9B0142458020D9BCD4351D38"
  },
  "custom3": {
    "code": "CEN3PRO1",
    "value": "5A0F9AF6B92E34468698040C915688BF"
  },
  "custom4": {
    "code": "TRAINING",
    "value": "3F54AE68BA66EF49A5984E5197202A4D"
  },
  "endDate": "2018-07-03",
  "endTime": "22:00",
  "everSentBack": false,
  "expenses": [],
  "highestExceptionLevel": "WARNING",
  "lastModified": "2018-05-25T08:08:59.000Z",
  "mainDestination": {
    "countryCode": "FR",
    "countrySubDivisionCode": "FR-69",
    "city": "Lyon, FRANCE",
    "name": "Lyon, FRANCE"
  },
  "name": "Company Training - JULY 2018",
  "owner": {
    "firstName": "John",
    "id": "c0d9894b-98e2-48d5-86f9-1decde90dd15",
    "lastName": "Doe"
  },
  "pendingApproval": false,
  "policy": {
    "id": "F4C8BD31CA9D4D6292795BE687EB9B2A"
  },
  "requestId": "333U",
  "startDate": "2018-07-01",
  "startTime": "07:15",
  "totalApprovedAmount": {
    "value": 0,
    "currency": "USD"
  },
  "totalPostedAmount": {
    "value": 0,
    "currency": "USD"
  },
  "totalRemainingAmount": {
    "value": 0,
    "currency": "USD"
  },
  "travelAgency": {
    "href": "https://us.api.concursolutions.com/travelrequest/v4/travelagencies/2EC038D7C3CBBE4ABA0914425064D34F",
    "id": "2EC038D7C3CBBE4ABA0914425064D34F",
    "template": "https://https://us.api.concursolutions.com/travelrequest/v4/travelagencies/{id}"
  },
  "type": {
    "code": "TRAVEL",
    "label": "Travel"
  },
  "operations": [
    {
      "rel": "submit",
      "href": "https://us.api.concursolutions.com/travelrequest/v4/requests/CED5E9CD8FC1424488F9331ACF956E73/submit"
    }
  ]
}

Get the list of existing Requests

Scopes

travelrequest.write - Refer to Scope Usage for full details.

HTTP Request

URI Template
GET {datacenter}/travelrequest/v4/requests

Parameters

Name Type Format Description
view string - Name of the view defining the scope of the Requests to get. Supported values:ALL: Get all existing Requests for a user (relevant only for the traveler).
ACTIVEGet all active Requests. Does not include cancelled Requests. Approved Requests included are aged less than three months based on current date and must not be in closed status.
UNSUBMITTED: Get all the unsubmitted Requests (relevant only for the traveler).
PENDING: Get all the Requests that are submitted but not yet approved (relevant only for the traveler).
VALIDATED: Get all the approved Requests for a user (relevant only for the traveler). Closed Requests are included in this view.
APPROVED: Get all the approved Requests by a user (relevant only for the approver). Closed Requests are included in this view.
CANCELED: Get all the cancelled Requests for a user (relevant only for the traveler). Cancelled could include closed/not closed Requests.
CLOSED: Get all the closed Requests for a user (relevant only for the traveler). Includes canceled then closed Request as well as approved then closed Requests.
SUBMITTED: Get all the submitted Requests for a user (relevant only for the traveler). Submitted does not include cancelled requests.
TOAPPROVE: Get all Requests to be approved by the user (relevant only for the approver).
PENDINGEBOOKING: Approved Requests awaiting Concur Travel booking(s).
PENDINGPROPOSAL: Get all Requests submitted to a Travel Agency (TMC) step (relevant only for the TMC agent), userId is required.
PROPOSALAPPROVED: Get all the approved Requests by a user (relevant only for the TMC agent), userId is required.
PROPOSALCANCELED: Get all the cancelled Requests for a user (relevant only for the TMC agent), userId is required.
If no view value is sent, the default view ALL will be used.
userId string - Associated with a traveler view: the unique identifier of the Request owner to use when searching for Requests.
Associated with an approver view: the unique identifier of the approver to user when searching for Requests.
Associated with a TMC agent view, Required, the unique identifier of the TMC agent to use. This TMC agent user must have a default Travel Agency assigned in its profile corresponding to the Travel Agency assigned to the Requests
start integer - Pagination: index of the first record. Default: 0
limit integer - Number of records to return per page. Default: 10. Maximum limit: 100, if higher value or digit value is set, a 400 error code will be displayed.
approvedBefore dateTime yyyy-MM-dd'T'HH:mm:ss'Z' or yyyy-MM-dd Returns Requests that have been approved before the specified date and time. This search term can be used along with other search terms to narrow the results. The date and time should be in UTC. when time is missing it is defaulted to midnight.
approvedAfter dateTime yyyy-MM-dd'T'HH:mm:ss'Z' or yyyy-MM-dd Returns Requests that have been approved after the specified date and time. This search term can be used along with other search terms to narrow the results. The date and time should be in UTC. When time is missing it is defaulted to midnight.
modifiedBefore dateTime yyyy-MM-dd'T'HH:mm:ss'Z' or yyyy-MM-dd Returns Requests in which the associated dependents (Header, Expected expenses, Segments, Allocations, Attendees, Comments) were modified before the specified date and time. This search term can be used along with other search terms to narrow the results. The date and time should be in UTC. When time is missing it is defaulted to midnight.
modifiedAfter dateTime yyyy-MM-dd'T'HH:mm:ss'Z' or yyyy-MM-dd Returns Requests in which the associated dependents (Header, Expected expenses, Segments, Allocations, Attendees, Comments) were modified after the specified date and time. This search term can be used along with other search terms to narrow the results. The date and time should be in UTC. When time is missing it is defaulted to midnight.
sortField string - The name of the field on which to sort. Supported values: startDate, approvalStatus, requestId. If no view value is sent, the default sortField startDate will be used.
sortOrder string - Sort order. Supported values: ASC, DESC. If no view value is sent, the default sortOrder DESC will be used.

Payload

None.

HTTP Response

HTTP Status Codes

To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.

Payload

List of Request

Example

HTTP Request

GET https://us.api.concursolutions.com/travelrequest/v4/requests?view=ALL&limit=10&start=0
Accept: application/json
Authorization: Bearer {token}

HTTP Response

200 OK
{
  "data": [{
      "href": "https://us.api.concursolutions.com/travelrequest/v4/requests/2B19A2438CD6664A9C44E0F4D39E870A",
      "id": "2B19A2438CD6664A9C44E0F4D39E870A",
      "approvalStatus": {
        "code": "SUBMITTED",
        "name": "Submitted & Pending Approval"
      },
      "approved": false,
      "approver": {
        "id": "86ac9588-5032-3fa7-b3cc-20e97d2d7146",
        "firstName": "Jason",
        "lastName": "McCafee"
      },
      "businessPurpose": "PMP Training in Nantes",
      "canceledPostApproval": false,
      "closed": false,
      "comment": "Plane too early in the morning, if possible book Hotel and arrive the day before\n",
      "creationDate": "2018-09-03T11:53:02.000Z",
      "endDate": "2018-10-08",
      "everSentBack": true,
      "expenses": [],
      "name": "PMP Training - OCTOBER",
      "owner": {
        "firstName": "John",
        "id": "c0d9894b-98e2-48d5-86f9-1decde90dd15",
        "lastName": "Doe"
      },
      "pendingApproval": true,
      "requestId": "3AT7",
      "startDate": "2018-10-08",
      "startTime": "05:00",
      "submitDate": "2018-09-03T11:55:00.000Z",
      "totalApprovedAmount": {
        "value": 213.06,
        "currency": "USD"
      },
      "totalPostedAmount": {
        "value": 213.06,
        "currency": "USD"
      },
      "totalRemainingAmount": {
        "value": 213.06,
        "currency": "USD"
      },
      "type": {
        "code": "TRAVEL",
          "label": "Travel"
      }
    },
    {
      "href": "https://us.api.concursolutions.com/travelrequest/v4/requests/4CCBAE73F3E14346AE93253480F5C409",
      "id": "4CCBAE73F3E14346AE93253480F5C409",
      "approvalStatus": {
        "code": "NOT_SUBMITTED",
        "name": "Not Submitted"
      },
      "approved": false,
      "businessPurpose": "Client meeting for project KIWI",
      "canceledPostApproval": false,
      "closed": false,
      "comment": "Need to arrive the day before as meeting is in Company office early in the morning\n",
      "creationDate": "2018-09-03T11:44:10.000Z",
      "endDate": "2018-09-20",
      "everSentBack": false,
      "expenses": [],
      "name": "Client meeting in Berlin",
      "owner": {
        "firstName": "John",
        "id": "c0d9894b-98e2-48d5-86f9-1decde90dd15",
        "lastName": "Doe"
      },
      "pendingApproval": false,
      "requestId": "3AT6",
      "startDate": "2018-09-18",
      "startTime": "17:30",
      "submitDate": "2018-09-03T11:49:32.000Z",
      "totalApprovedAmount": {
        "value": 478.56,
        "currency": "USD"
      },
      "totalPostedAmount": {
        "value": 478.56,
        "currency": "USD"
      },
      "totalRemainingAmount": {
        "value": 478.56,
        "currency": "USD"
      },
      "type": {
        "code": "TRAVEL",
          "label": "Travel"
      }
    }
  ],
  "operations": [{
      "rel": "next",
      "href": "https://us.api.concursolutions.com/travelrequest/v4/requests?view=ALL&limit=3&start=3"
    },
    {
      "rel": "first",
      "href": "https://us.api.concursolutions.com/travelrequest/v4/requests?view=ALL&limit=3&start=0"
    },
    {
      "rel": "last",
      "href": "https://us.api.concursolutions.com/travelrequest/v4/requests?view=ALL&limit=3&start=135"
    }
  ]
}

Get the content of an existing Request

Scopes

travelrequest.write - Refer to Scope Usage for full details.

HTTP Request

URI Template
GET {datacenter}/travelrequest/v4/requests/{requestUuid}

Parameters

Name Type Format Description
requestUuid string - Required The unique identifier of the Request.
userId string - The unique identifier of the user getting the content of the Request. If empty when using a Company token the default system user will be assumed to perform the action.

Payload

None.

HTTP Response

HTTP Status Codes

To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.

Payload

Request - The Request having {requestUuid} as unique identifier.

Example

HTTP Request

GET https://us.api.concursolutions.com/travelrequest/v4/requests/224AF3CDCC2A5244A37C72FA5770C6F2
Accept: application/json
Authorization: Bearer {token}

HTTP Response

200 OK
{
  "href": "https://us.api.concursolutions.com/travelrequest/v4/requests/224AF3CDCC2A5244A37C72FA5770C6F2",
  "id": "224AF3CDCC2A5244A37C72FA5770C6F2",
  "approvalStatus": {
    "code": "NOT_SUBMITTED",
    "name": "Not Submitted"
  },
  "approved": false,
  "businessPurpose": "Client meeting for project KIWI",
  "canceledPostApproval": false,
  "cashAdvances": {
    "href": "https://us.api.concursolutions.com/travelrequest/v4/requests/224AF3CDCC2A5244A37C72FA5770C6F2/cashadvances",
    "id": "224AF3CDCC2A5244A37C72FA5770C6F2",
    "template": "https://us.api.concursolutions.com/travelrequest/v4/requests/{id}/cashadvances"
  },
  "closed": false,
  "comment": "Need to arrive the day before for meeting in Company Office",
  "comments": {
    "href": "http://us.api.concursolutions.com/travelrequest/v4/requests/224AF3CDCC2A5244A37C72FA5770C6F2/comments",
    "id": "224AF3CDCC2A5244A37C72FA5770C6F2",
    "template": "http://us.api.concursolutions.com/travelrequest/v4/requests/{id}/comments"
  },
  "creationDate": "2018-05-25T07:31:33.000Z",
  "custom1": {
    "value": "Kick-off meeting for project KIWI"
  },
  "custom2": {
    "code": "CEN1",
    "value": "54F0CBD8833CB348BD45A6C7C621C951"
  },
  "custom3": {
    "code": "CEN1PRO2",
    "value": "441D6FC50766A044ACC07FF780F1BAD9"
  },
  "custom4": {
    "code": "CLIENTPROJECT",
    "value": "050BE16A7BF72948810AFDBC9069BD8E"
  },
  "endDate": "2018-07-17",
  "endTime": "19:30",
  "everSentBack": false,
  "exceptions": {
    "href": "https://us.api.concursolutions.com/travelrequest/v4/requests/224AF3CDCC2A5244A37C72FA5770C6F2/exceptions",
    "id": "224AF3CDCC2A5244A37C72FA5770C6F2",
    "template": "https://us.api.concursolutions.com/travelrequest/v4/requests/{id}/exceptions"
  },
  "expensePolicy": {
    "id": "A6D42A825114472FAF402180E20B3751"
  },
  "expenses": [
    {
      "href": "https://us.api.concursolutions.com/travelrequest/v4/expenses/B5FB8991E390474E875D6FD5BB1FDAF1",
      "id": "B5FB8991E390474E875D6FD5BB1FDAF1",
      "template": "https://us.api.concursolutions.com/travelrequest/v4/expenses/{id}"
    },
    {
      "href": "https://us.api.concursolutions.com/travelrequest/v4/expenses/D65BDBD5D980F6498D67A92B06A457B0",
      "id": "D65BDBD5D980F6498D67A92B06A457B0",
      "template": "hhttps://us.api.concursolutions.com/travelrequest/v4/expenses/{id}"
    },
    {
      "href": "https://us.api.concursolutions.com/travelrequest/v4/expenses/C286A46A2DDF984EA28E41CEA278667D",
      "id": "C286A46A2DDF984EA28E41CEA278667D",
      "template": "https://us.api.concursolutions.com/travelrequest/v4/expenses/{id}"
    }
  ],
  "lastModified": "2018-05-25T07:34:01.000Z",
  "mainDestination": {
    "countryCode": "DE",
    "countrySubDivisionCode": "DE-BE",
    "city": "Berlin, GERMANY",
    "name": "Berlin, GERMANY"
  },
  "name": "Client meeting in Berlin - JULY",
  "owner": {
    "firstName": "John",
    "id": "c0d9894b-98e2-48d5-86f9-1decde90dd15",
    "lastName": "Doe"
  },
  "pendingApproval": false,
  "policy": {
    "id": "00497B95D8055849A1B217C8D05FFB86"
  },
  "requestId": "333T",
  "startDate": "2018-07-15",
  "startTime": "06:00",
  "totalApprovedAmount": {
    "value": 494.56,
    "currency": "USD"
  },
  "totalPostedAmount": {
    "value": 494.56,
    "currency": "USD"
  },
  "totalRemainingAmount": {
    "value": 494.56,
    "currency": "USD"
  },
  "travelAgency": {
    "href": "https://us.api.concursolutions.com/travelrequest/v4/travelagencies/2EC038D7C3CBBE4ABA0914425064D34F",
    "id": "2EC038D7C3CBBE4ABA0914425064D34F",
    "template": "https://us.api.concursolutions.com/travelrequest/v4/travelagencies/{id}"
  },
  "type": {
    "code": "TRAVEL",
    "label": "Travel"
  },
  "operations": [
    {
      "rel": "submit",
      "href": "https://us.api.concursolutions.com/travelrequest/v4/requests/224AF3CDCC2A5244A37C72FA5770C6F2/submit"
    }
  ]
}

Update the content of an existing Request

Update of the following fields is supported : comment, startDate, startTime, endDate, endTime, expensePolicy, name, businessPurpose, mainDestination, travelAgency, and custom fields. Other fields will be ignored.

This endpoint supports partial update. You may submit only the fields to update in the body, fields not present in the body will remain unchanged. To clear a field use the value null (without quotes).

id field is not mandatory in the payload, if provided the value must match the requestUuid parameter.

Scopes

travelrequest.write - Refer to Scope Usage for full details.

HTTP Request

URI Template
PUT {datacenter}/travelrequest/v4/requests/{requestUuid}

Parameters

Name Type Format Description
requestUuid string - Required The unique identifier of the Request.
userId string - The unique identifier of the user performing the update. Required when connecting with a Company token. If empty a 400, missingRequiredParam error code will be displayed.

Payload

Request

HTTP Response

HTTP Status Codes

To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.

Payload

Request - The Request having {requestUuid} as unique identifier after update.

Example

HTTP Request

PUT https://us.api.concursolutions.com/travelrequest/v4/requests/E82B0B803671004B9A5D952F34FBD01E
Content-Type: application/json
Accept: application/json
Authorization: Bearer {token}
{
  "businessPurpose": "Trip to Lyon for company training - Modification of dates and Cost center + Custom Field",
  "comment": "Company training requires to go to Lyon - Dates and service changed",
  "custom1": {
    "value": "Training part of IT Service"
  },
  "custom2": {
    "value": "54F0CBD8833CB348BD45A6C7C621C951"
  },
  "custom3": {
    "value": "441D6FC50766A044ACC07FF780F1BAD9"
  },
  "custom4": {
    "value": "3F54AE68BA66EF49A5984E5197202A4D"
  },
  "endDate": "2018-07-09",
  "endTime": "19:00",
  "id": "053A479B3C9DD847B02A203C657AE26B",
  "startDate": "2018-07-07",
  "startTime": "06:15",
  "name": "Company Training - JULY 2018",
  "mainDestination": {
    "city": "Lyon, FRANCE",
    "countryCode": "FR",
    "countrySubDivisionCode": "FR-69",
    "name": "Lyon, FRANCE"
  },
  "policy": {
    "id": "F4C8BD31CA9D4D6292795BE687EB9B2A"
  },
  "travelAgency": {
    "id": "2EC038D7C3CBBE4ABA0914425064D34F"
  }
}

HTTP Response

200 OK
{
  "href": "https://us.api.concursolutions.com/travelrequest/v4/requests/053A479B3C9DD847B02A203C657AE26B",
  "id": "053A479B3C9DD847B02A203C657AE26B",
  "approvalStatus": {
    "code": "NOT_SUBMITTED",
    "name": "Not Submitted"
  },
  "approved": false,
  "businessPurpose": "Trip to Lyon for company training - Modification of dates and Cost center + Custom Field",
  "canceledPostApproval": false,
  "closed": false,
  "comment": "Company training requires to go to Lyon - Dates and service changed",
  "creationDate": "2018-05-25T09:17:25.000Z",
  "custom1": {
    "value": "Training part of IT Service"
  },
  "custom2": {
    "code": "CEN1",
    "value": "54F0CBD8833CB348BD45A6C7C621C951"
  },
  "custom3": {
    "code": "CEN1PRO2",
    "value": "441D6FC50766A044ACC07FF780F1BAD9"
  },
  "custom4": {
    "code": "TRAINING",
    "value": "3F54AE68BA66EF49A5984E5197202A4D"
  },
  "endDate": "2018-07-09",
  "endTime": "19:00",
  "everSentBack": false,
  "expenses": [],
  "lastModified": "2018-05-25T09:24:34.000Z",
  "mainDestination": {
    "countryCode": "FR",
    "countrySubDivisionCode": "FR-69",
    "city": "Lyon, FRANCE",
    "name": "Lyon, FRANCE"
  },
  "name": "Company Training - JULY 2018",
  "owner": {
    "firstName": "John",
    "id": "c0d9894b-98e2-48d5-86f9-1decde90dd15",
    "lastName": "Doe"
  },
  "pendingApproval": false,
  "policy": {
    "id": "F4C8BD31CA9D4D6292795BE687EB9B2A"
  },
  "requestId": "333X",
  "startDate": "2018-07-07",
  "startTime": "06:15",
  "totalApprovedAmount": {
    "value": 0,
    "currency": "USD"
  },
  "totalPostedAmount": {
    "value": 0,
    "currency": "USD"
  },
  "totalRemainingAmount": {
    "value": 0,
    "currency": "USD"
  },
  "travelAgency": {
    "href": "https://us.api.concursolutions.com/travelrequest/v4/travelagencies/2EC038D7C3CBBE4ABA0914425064D34F",
    "id": "2EC038D7C3CBBE4ABA0914425064D34F",
    "template": "https://us.api.concursolutions.com/travelrequest/v4/travelagencies/{id}"
  },
  "type": {
    "code": "TRAVEL",
    "label": "Travel"
  },
  "operations": [
    {
      "rel": "submit",
      "href": "https://us.api.concursolutions.com/travelrequest/v4/requests/053A479B3C9DD847B02A203C657AE26B/submit"
    }
  ]
}

Delete an existing Request

Scopes

travelrequest.write - Refer to Scope Usage for full details.

HTTP Request

URI Template
DELETE {datacenter}/travelrequest/v4/requests/{requestUuid}

Parameters

Name Type Format Description
requestUuid string - Required The unique identifier of the Request.
userId string - The unique identifier of the user performing the deletion. Required when connecting with a Company token. If empty a 400, missingRequiredParam error code will be displayed.

Payload

None.

HTTP Response

Payload

None.

Example

HTTP Request

DELETE https://us.api.concursolutions.com/travelrequest/v4/requests/0D4DC4589D33AC4B9AF2E8B548C7AD2C
Accept: application/json
Authorization: Bearer {token}

HTTP Response

200 OK
true

Get the list of comments for an existing Request

Scopes

travelrequest.write - Refer to Scope Usage for full details.

HTTP Request

URI Template
GET {datacenter}/travelrequest/v4/requests/{requestUuid}/comments

Parameters

Name Type Format Description
requestUuid string - Required The unique identifier of the Request.

Payload

None.

HTTP Response

HTTP Status Codes

To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.

Payload

Comments

Example

HTTP Request

GET https://us.api.concursolutions.com/travelrequest/v4/requests/224AF3CDCC2A5244A37C72FA5770C6F2/comments
Accept: application/json
Authorization: Bearer {token}

HTTP Response

200 OK
[
  {
    "author": {
      "firstName": "Steve",
      "lastName": "Smith"
    },
    "creationDateTime": "2019-07-12T11:51:14.000Z",
    "isLatest": true,
    "value": "Please specify an amount less than 600 Euros"
  },
  {
    "author": {
      "firstName": "John",
      "lastName": "Doe"
    },
    "creationDateTime": "2019-07-12T11:11:39.000Z",
    "isLatest": false,
    "value": "Please review the business meal excepted expense to confirm required amount"
  }
]

Get the list of cash advances assigned to an existing Request

Scopes

travelrequest.write - Refer to Scope Usage for full details.

HTTP Request

URI Template
GET {datacenter}/travelrequest/v4/requests/{requestUuid}/cashadvances

Parameters

Name Type Format Description
requestUuid string - Required The unique identifier of the Request.
userId string - The unique identifier of the user getting the list of the cash advances assigned to a Request. Required when connecting with a Company token. If empty, a 400 missingRequiredParam error code will be displayed.

Payload

None.

HTTP Response

HTTP Status Codes

To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.

Payload

ResourceLink - The resource link leading to the created cash advance.

Example

HTTP Request

GET https://us.api.concursolutions.com/travelrequest/v4/requests/224AF3CDCC2A5244A37C72FA5770C6F2/cashadvances
Accept: application/json
Authorization: Bearer {token}

HTTP Response

200 OK
[
    {
        "href": "https://us.api.concursolutions.com/travelrequest/v4/cashadvances/EF3E237ACAA3C449B808BA75BDD049FA",
        "id": "EF3E237ACAA3C449B808BA75BDD049FA",
        "template": "https://us.api.concursolutions.com/travelrequest/v4/cashadvances/{id}"
    },
    {
        "href": "https://us.api.concursolutions.com/travelrequest/v4/cashadvances/9DDAB28B89828A4497209062F4AF87D6",
        "id": "9DDAB28B89828A4497209062F4AF87D6",
        "template": "https://us.api.concursolutions.com/travelrequest/v4/cashadvances/{id}"
    }
]

Get the list of exceptions linked to an existing Request

Scopes

travelrequest.write - Refer to Scope Usage for full details.

HTTP Request

URI Template
GET {datacenter}/travelrequest/v4/requests/{requestUuid}/exceptions

Parameters

Name Type Format Description
requestUuid string - Required The unique identifier of the Request.
userId string - The unique identifier of the user getting the content of the exceptions. Required when connecting with a Company token. If empty, a 400 missingRequiredParam error code will be displayed.

Payload

None.

HTTP Response

HTTP Status Codes

To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.

Payload

Exceptions

Example

HTTP Request

GET https://us.api.concursolutions.com/travelrequest/v4/requests/224AF3CDCC2A5244A37C72FA5770C6F2/exceptions
Accept: application/json
Authorization: Bearer {token}

HTTP Response

200 OK
[
    {
        "code": "CALWARN2",
        "level": 1,
        "message": "The requested Cash Advance exceeds the limit allowed by your company policy which is defined as the total of Daily Allowances (€0.00). Please update the requested amount accordingly.",
        "isBlocking": false,
        "source": {
            "id": "DAF37B097DB82D4D9A15E9F3F7E460C9",
            "href": "https://emea.api.concursolutions.com/v4/requests/DAF37B097DB82D4D9A15E9F3F7E460C9?compact=false",
            "type": "HEADER"
        },
        "parameters": {}
    }
]

Travel Request v4 - Endpoints - Schemas

Schema

Request

Name Type Format Description
approvalLimitDate timestamp [RFC 3339] yyyy-MM-dd'T'HH:mm:ss.SSS'Z' The date by which the Request must be approved. This element appears only when integrated with Concur Travel.
approvalStatus object Approval Status The approval status of the Request.
approved boolean - Indicates whether this Request is approved.
approver object Employee The approver to whom the Request was sent.
authorizedDate timestamp [RFC 3339] yyyy-MM-dd'T'HH:mm:ss.SSS'Z' For approved Request, the date at which the approval process was completed.
businessPurpose string - The business purpose of the Request.
canceledPostApproval boolean - Indicates whether this Request was canceledPostApproval.
cashAdvances object ResourceLink The list of cash advances for this Request.
closed boolean - Indicates whether this Request is closed.
comment string - The last comment attached to this Request.
comments object ResourceLink The list of comments for this Request.
creationDate timestamp [RFC 3339] yyyy-MM-dd'T'HH:mm:ss.SSS'Z' The date the Request was created.
custom1 to custom20 object CustomField The details from the Custom fields. These fields may not have data, depending on the configuration.
endDate date [ISO 8601] yyyy-MM-dd The end date of the Request.
endTime time [ISO 8601] yyyy-MM-dd The end time of the Request.
everSentBack boolean - Indicates whether the Request has ever been sent back to the employee.
exceptions object ResourceLink The list of exceptions that have been raised to this Request.
expenses array ResourceLink Expected expenses attached to this Request.
extensionOf object RequestLink The Request that this Request is an extension of, or addendum to.
highestExceptionLevel string - The highest level of exception contained in this Request. Supported values: WARNING, ERROR, and NONE
href string [RFC 3986] Hyperlink to the resource for this Request.
id string - The unique identifier of the Request.
lastModified timestamp [RFC 3339] yyyy-MM-dd'T'HH:mm:ss.SSS'Z' The date the Request was last modified.
mainDestination object Location The main destination of the Request.
name string - The name of the Request.
owner object Employee The employee who owns the Request.
pendingApproval boolean - Indicates whether this Request is pending approval.
policy object ResourceLink The policy that applies to the Request.
requestId string 4 to 6 alphanumeric characters The public key of the Request (unique per customer).
startDate date [ISO 8601] yyyy-MM-dd The start date of the Request.
startTime time [ISO 8601] yyyy-MM-dd The start time of the Request.
submitDate timestamp [RFC 3339] yyyy-MM-dd'T'HH:mm:ss.SSS'Z' The date the Request was submitted (last submit date in case of recall).
totalApprovedAmount object Amount The total amount of approved expected expenses in the Request, expressed in the reimbursement currency of the employee at the time they created the Request.
totalPostedAmount object Amount The total amount of the Request, expressed in the reimbursement currency of the employee at the time they created the Request.
totalRemainingAmount object Amount The total amount not included in an Expense report, expressed in the reimbursement currency of the employee at the time they created the Request.
travelAgency object ResourceLink The travel agency office that is managing the trip associated to this Request.
operations array Link Links to operations available for the Request, depends on the current workflow status.
type object RequestType The type of the Request, inherited from the Request Policy Type.

Amount

Name Type Format Description
value number - Required The amount in the defined currency.
currency string [ISO 4217:2015] Required The 3-letter ISO 4217 code for the currency in which the amount is expressed.

Approval Status

Name Type Format Description
code string - The code for the approval status of the Request. Supported values: NOT_SUBMITTED, SUBMITTED, APPROVED, CANCELED, or SENTBACK
name string - The approval status of the Request in the current user's language.

Cash Advance

Name Type Format Description
amountRequested object Amount The amount of the cash advance in the Request, expressed in the currency of the requested cash advance.
For the Cash Advance detail endpoint only, the Amount schema will contain an additional amount field for feature parity purpose with the new planned Cash Advance API part of the cash advance service. The value field will be soon deprecated, it is highly recommended to rely on the amount field in that case.
approvalStatus object Cash Advance Approval Status The approval status of the cash advance.
cashAdvanceId string - The unique identifier of the cash advance.
comment string - The last comment related to this cash advance.
exchangeRate object Exchange Rate The exchange rate that applies to the cash advance.
issueDate timestamp [RFC 3339] yyyy-MM-dd'T'HH:mm:ss.SSS The date the cash advance was issued.
requestDate timestamp [RFC 3339] yyyy-MM-dd'T'HH:mm:ss.SSS The date the cash advance was submitted (last submit date in case of recall).

Cash Advance Approval Status

Name Type Format Description
code string - The code for the approval status of the cash advance. Supported values: C_PEND, C_APPR, C_COMP, C_FILE, C_ISSU, C_NISU, C_NOTF, C_PECA, or C_REJE
name string - The approval status of the cash advance in the current user's language.

Comments

Name Type Format Description
author object Employee The employee who has created the comment in the expected expense.
creationDate timestamp [RFC 3339] yyyy-MM-dd'T'HH:mm:ss.SSS Creation date of the comment.
isLatest boolean - If true, the comment has been edited since the last workflow transition.
value string - The value of the comment.

CustomField

Name Type Format Description
code string - The short code for the list item. For non-list fields, this value will be blank.
value string - The value of the non-list item. For list fields, this is the unique id of the list item.
href string - The link to get this list item on the list service. Empty for non-list items.

Retrieving the listItemId requires to call the List API, which is currently being worked on for externalisation. In the meantime, to fill in a custom list item for the creation of a Request or an Expected Expense, clients may use one of the following workaround: * Use the copy down configuration feature to update custom fields from the Employee profile to the Request header, and from the Request header to the Expected expense. * For a limited number of list items that are part of a custom field, a Request containing those values in the related custom fields may be manually created. The list item unique id will then be retrieved by calling the get detail of this Request. The same process is used for all list items values of the list.

Employee

Name Type Format Description
firstName string - The first name of the employee.
href string [RFC 3986] Hyperlink to the resource.
id string [RFC 4122] Unique identifier of the related object.
lastName string - The last name of the employee.
middleInitial string - The middle initial of the employee.
template string - Hyperlink template to the resource.

Exceptions

Name Type Format Description
code string - The system exception code defined for the exception. Example: BADCODE
isBlocking boolean - Defines whether the exception will prevent the Request from being submitted.
level integer - The numeric level associated with the exception. Example: 99
message string - The user facing message defined for the exception.
source array Exception source The source that has raised the exception.
parameters map missingFields: array of missing field labels
missingFieldsIds: array of missing field ids
For missing fields exceptions, additional values giving more label and ids of the missing fields. Example : parameters : { "missingFields" : ["Request Name", "Purpose"], "missingFieldsIds" : [ "Name", "Purpose" ] }

Exception Source

Name Type Format Description
href string [RFC 3986] Hyperlink to the resource.
id string [RFC 4122] Unique identifier of the source.
type string - Defines the type of the source. Supported values: ALLOCATION, CASH_ADVANCE, EXPENSE, and HEADER
Name Type Format Description
rel string [RFC 5988] Relation type as defined by the server. There are registered relation types listed in RFC 5988 6.2.2. Initial Registry Contents including pagination relation types of next, prev, first and last.
href string [RFC 3986] Hyperlink to the resource.

List of Request

Name Type Format Description
data array Request List of Requests in the page requested.
operations array Link Links to next, prev, first and last pages.

List of Request Policies

Name Type Format Description
- array Request Policy List of active Requests policies for a given user.

Location

Name Type Format Description
city string - Required for all city location type (not airport, or rail station - except for STD location type) The city name of the location.
Note: STD location type for rail is considered as a city location type, city and countryCode fields are required in that case.
countryCode string [ISO 3166-1] Required if city or name is used The ISO 3166-1 country code.
countrySubDivisionCode string [ISO 3166-2] The ISO 3166-2 country sub code.
iataCode string - Required if air is used The IATA code of an airport location.
id string - The id of the location.
latitude number - The latitude of the location.
locationCode string - Required if rail is used with RAIL_xx locationType The code of the location. Optional for segments based on city locations (will be required in case of duplicate locations within database).
locationType string - Required if rail is used The type of the location.
longitude number - The longitude of the location.
name string - The name of the location. Always provide the countryCode value in addition to the name.

Below are the different node expected in the POST endpoints by location type (City, Rail station, or Airport) - example for endLocation field:

Airport json "endLocation": { "city": "Moscow", "name": "Sheremetyevo", "countryCode": "RU", "iataCode": "SOV" }

City json "endLocation": { "city": "Vienna", "countryCode": "AT" }

Rail station (locationCode exists, locationType depends of rail provider) json "endLocation": { "name": "MARSEILLE ST CHARLES", "countryCode": "FR", "locationCode": "FRMSC", "locationType": "RAIL_2C" } Location types for Rail :

Location Type Railway company
RAIL_0Z Swiss Federal Railways
RAIL_2A Deutsche Bahn AG
RAIL_2C SNCF
RAIL_2H Thalys International
RAIL_2R VIA Rail Canada Inc.
RAIL_2V Amtrak
RAIL_9F Eurostar International Limited
RAIL_XH China Railway
RAIL_Z0 UK Rail
STD Standard locations
Name Type Format Description
href string [RFC 3986] Hyperlink to the resource.
id string [RFC 4122] Unique identifier of the related object.
template string - Hyperlink template to the resource.
Name Type Format Description
requestId string 4 to 6 alphanumeric characters The public key of the Request (unique per customer).

Request Policy

Name Type Format Description
href string [RFC 3986] Hyperlink to the resource for this Request policy.
id string - The Request policy unique identifier.
name string - The name of the Request policy.

Request Type

Name Type Format Description
code string - The code of the type inherited from the Request Policy type. Possible values: Authorization, Cash Advance, Travel.
label string - The label of the type inherited from the Request Policy Type.

Expected Expense

Name Type Format Description
allocations object Allocation The details of the allocations for this expected expense.
approvedAmount object Amount The approved amount of the expected expense entry, in the transaction currency of the Request.
budgetAccrualDate timestamp [RFC 3339] yyyy-MM-dd'T'HH:mm:ss.SSS'Z' The date to determine which budgets are affected.
businessPurpose string - The business purpose of the Request entry.
comments object ResourceLink The list of comments for this expected expense.
custom1 to custom40 object CustomField The details from the Custom fields. These fields may not have data, depending on the configuration.
exchangeRate object Exchange Rate The exchange rate that applies to the entry.
expenseType object Expense Type The expense type of the entry. Required for expected expenses, automatically set for segments depending on the SegmentType code.
href string [RFC 3986] Hyperlink to the resource for this Request entry.
id string - The unique identifier of the expected expense entry.
lastComment string - The last comment (most recent) of the expected expense entry.
lastModifiedDate timestamp [RFC 3339] The date when this expected expense was last modified.
location object Location The location of the expected expense entry.
orgUnit1 to orgUnit6 object Amount The details from the Custom fields. These fields may not have data, depending on the configuration.
postedAmount object Amount The posted amount of the expected expense entry, in the transaction currency of the Request.
parentRequest object ResourceLink The parent Request of the expected expense.
remainingAmount object Amount The remaining amount of the expected expense entry, in the transaction currency of the Request.
source enum - The source that created the expected expense. Supported values: CASH_ADVANCE or TRAVEL_ALLOWANCE. This field will be empty in any other case
transactionAmount object Amount Required The amount of the expected expense entry, in the transaction currency paid to the vendor.
transactionDate timestamp [RFC 3339] yyyy-MM-dd'T'HH:mm:ss.SSS'Z' Required The date of the transaction.
travelAllowance object Travel Allowance The Travel allowance.
tripData object Trip Data The description of the trip.
vendor object Vendor The vendor of the expected expense entry.

Allocation

Name Type Format Description
allocationAmount object Amount The amount of the allocation calculated with the percentage value multiplied by the transaction amount on the expected expense. This amount is given in the transaction's currency and rounded to eight digits after the decimal point.
approvedAmount object Amount The amount of the allocation calculated with the percentage value multiplied by the approved amount on the expected expense. This amount is given in the user's currency and rounded to eight digits after the decimal point.
allocationId string - The unique allocation identifier.
custom1 to custom20 object CustomField The details from the Custom fields. These fields may not have data, depending on the configuration.
expenseId string - The unique identifier of the expected expense associated with the allocation.
percentEdited boolean - Whether the allocation percent has been edited.
percentage number - The percentage of the total expected expense that this allocation represents.
postedAmount object Amount The amount of the allocation calculated with the percentage value multiplied by the posted amount on the expected expense. This amount is given in the user's currency and rounded to eight digits after the decimal point.
systemAllocation boolean - Whether the allocation is a system allocation, usually hidden from the user. If displayed to the user, should be read-only.

Exchange Rate

Name Type Format Description
operation string - Exchange rate operation. Supported values: MULTIPLY, DIVIDE
value number - Exchange rate value.

Expense Type

Name Type Format Description
id string - Required Unique identifier of the expense type.
name string - Name of the expense type.

List Item Field

Name Type Format Description
code string - The short code of the list item.
value string - Unique identifier of the list item.
href string [RFC 3986] Hyperlink to the resource for the list item.

Segment Leg

Name Type Format Description
class list List Item Field The booking class of the segment leg.
classOfService string - The class of service of the segment leg. For example, in the case of an air segment, this field would contain the one-letter booking code: Y for economy class, or F for first class.
comment string - Contains the last comment saved in this segment leg.
custom1 to custom40 object CustomField The details from the Custom fields. These fields may not have data, depending on the configuration.
endDate date [ISO 8601] YYYY-MM-DD The date of the end of this segment leg. It represents the arrival date of AIRFR and TRAIN segments, check out date for HOTEL, or drop off for CARRT.
endLocation object ResourceLink The location where this segment leg arrives. For example, the arrival location for an air segment.
endLocationDetail string - Details about the end location. This would contain details about the name of a hotel, or some details about a car rental agency for example.
endTime time [ISO 8601] HH:MM The time for the end of this segment leg.
id string - The unique identifier of the segment leg.
returnLeg boolean - Indicates whether this leg is the return leg of a round trip. In case of a ROUND_TRIP, if not explicitly set, the second segment leg will be considered as the return leg.
startDate date [ISO 8601] YYYY-MM-DD The date of the beginning of this segment leg.
startLocation object ResourceLink The start location of this segment leg. This would be the departure location for an air segment for example.
startLocationDetail string - Details about the start location. This would contain details about the name of a hotel, or some details about a car rental agency for example.
startTime time [ISO 8601] HH:MM The time for the beginning of this segment leg.
segmentLocator string - This is the identifier for Concur Travel segments (if applicable).
vendorName string - Contains the vendor description of the segment leg.

Segment Type

Name Type Format Description
category enum - Describes the category of this segment type. Supported values: REQ_SEG_AIRFR, REQ_SEG_CARRT, REQ_SEG_HOTEL, REQ_SEG_LIMOF, REQ_SEG_RAILF, REQ_SEG_TAXIF, REQ_SEG_MISC, REQ_SEG_PARKG, REQ_SEG_DININ, REQ_SEG_EVENT
code string - Required The code of the segment type. Supported values: AIRFR, CARRT, HOTEL, LIMOF, RAILF, TAXIF, MISC, PARKG, DININ, EVENT or custom codes

It can be REQ_SEG_AIRFR / AIRFR for a regular air segment, or REQ_SEG_AIRFR / 10325 for a custom air segment.

Example:

{
  "category": "REQ_SEG_AIRFR",
  "code": "AIRFR"
}

Travel Agency

Name Type Format Description
emailAddress string - The travel agency email address.
id string - The travel agency unique identifier.
name string - The travel agency office name.
proposalType string - The travel agency proposal type. Supported values: CWTF, AEBT, API

Travel Allowance

Name Type Format Description
dailyTravelAllowanceId string - The fixed daily travel allowance id associated with the expected expense.

Trip Data

Name Type Format Description
agencyBooked boolean - If true, this travel is (or has to be) handled by a travel agency.
legs list Segment Leg The list of the legs of the travel.
tripType string - Indicates the type of this trip. Supported values: ONE_WAY, ROUND_TRIP, or MULTI_STOPS. If not provided, will be detected from the given legs.
segmentType object Segment Type Required The type of the segment.
selfBooked boolean - If true, this travel has been reserved by Concur Travel, or if Concur Travel has retrieved the trip information in the GDS.

Vendor

Name Type Format Description
id string - The vendor identifier of the entry.
name string - The vendor description of the entry.

Travel Request v4 - Travel Agency Resources

Manage the configuration for Travel Agencies integrated with Concur Request.

Get the description of a Travel Agency

Scopes

travelrequest.write - Refer to Scope Usage for full details.

HTTP Request

URI Template
GET {datacenter}/travelrequest/v4/travelagencies/{agencyUuid}

Parameters

Name Type Format Description
agencyUuid string - Required The unique identifier of the Travel Agency.

Payload

None

HTTP Response

HTTP Status Codes

To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.

Payload

Travel Agency

Example

HTTP Request

GET https://us.api.concursolutions.com/travelrequest/v4/travelagencies/86B720AF168F1C4CA52E37AC710E897B
Accept: application/json
Authorization: Bearer {token}

HTTP Response

200 OK
{
  "href": "https://us.api.concursolutions.com/travelrequest/v4/travelagencies/86B720AF168F1C4CA52E37AC710E897B",
  "id": "2EC038D7C3CBBE4ABA0914425064D34F",
  "emailAddress": "agency-email@agencyname.com",
  "name": "myCompanyAgency"
}

Travel Request v4 - Workflow Resources

Manage workflow transitions for a Request.

Move an existing Request in the approval workflow

Scopes

travelrequest.write - Refer to Scope Usage for full details.

HTTP Request

The HATEOAS links for actions available given the current user and state are listed in the operations of the Request resource.

Traveler actions * submit: initiate the approval workflow. * recall: get back the Request, usually to modify the content. * cancel: cancel the Request and attached itineraries. * close: archive the Request. * reopen: get back an archived Request.

Non traveler actions (Approver / Processor / External Validation / TMC Agent)

URI Template
POST {datacenter}/travelrequest/v4/requests/{requestUuid}/{action}

Parameters

Name Type Format Description
requestUuid string - Required The unique identifier of the Request.
action string - Required The state transition to be executed. Supported values: submit, approve, recall, sendback, cancel, close, or reopen
comment string - Only works with when the workflow action is sendback. This comment is visible wherever Request comments are available to the employee, approver, and/or Request administrator.
userId string - The unique identifier of the user performing the status transition. Required when connecting with a Company token for traveler actions only. If empty, a 400 missingRequiredParam error code will be displayed. For non traveler actions, if not provided, "System, Concur" will be displayed in the Audit Trail of the Request.
companyID string - The unique identifier of the company.

Payload

None, except when the workflow action is sendback where an optional comment may be submitted

{ "comment" : "My Comment" }

This comment is visible wherever Request comments are available to the employee, approver, and/or Request administrator.

HTTP Response

HTTP Status Codes

To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.

Payload

Request - The Request having {requestUuid} as unique identifier.

Example

HTTP Request

POST https://us.api.concursolutions.com/travelrequest/v4/requests/053A479B3C9DD847B02A203C657AE26B/submit
Content-Type: application/json
Accept: application/json
Authorization: Bearer {token}

HTTP Response

200 OK
{
  "href": "https://us.api.concursolutions.com/travelrequest/v4/requests/053A479B3C9DD847B02A203C657AE26B",
  "id": "053A479B3C9DD847B02A203C657AE26B",
  "approvalStatus": {
    "code": "SUBMITTED",
    "name": "Submitted & Pending Approval"
  },
  "approved": false,
  "businessPurpose": "Trip to Lyon for company training - Modification of dates and Cost center + Custom Field",
  "canceledPostApproval": false,
  "closed": false,
  "creationDate": "2018-05-25T09:17:25.000Z",
  "custom1": {
    "value": "Training part of IT Service"
  },
  "custom2": {
    "code": "CEN1",
    "value": "54F0CBD8833CB348BD45A6C7C621C951"
  },
  "custom3": {
    "code": "CEN1PRO2",
    "value": "441D6FC50766A044ACC07FF780F1BAD9"
  },
  "custom4": {
    "code": "TRAINING",
    "value": "3F54AE68BA66EF49A5984E5197202A4D"
  },
  "endDate": "2018-07-09",
  "endTime": "19:00",
  "everSentBack": false,
  "expenses": [
    {
      "href": "https://us.api.concursolutions.com/travelrequest/v4/expenses/47C8AD9E382B5143BB54DC3090577C60",
      "id": "47C8AD9E382B5143BB54DC3090577C60",
      "template": "https://us.api.concursolutions.com/travelrequest/v4/expenses/{id}"
    }
  ],
  "lastModified": "2018-05-25T09:38:02.000Z",
  "mainDestination": {
    "countryCode": "FR",
    "countrySubDivisionCode": "FR-69",
    "city": "Lyon, FRANCE",
    "name": "Lyon, FRANCE"
  },
  "name": "Company Training - JULY 2018",
  "owner": {
    "firstName": "John",
    "id": "c0d9894b-98e2-48d5-86f9-1decde90dd15",
    "lastName": "Doe"
  },
  "pendingApproval": true,
  "policy": {
    "id": "F4C8BD31CA9D4D6292795BE687EB9B2A"
  },
  "requestId": "333X",
  "startDate": "2018-07-07",
  "startTime": "06:15",
  "submitDate": "2018-05-25T09:38:02.000Z",
  "totalApprovedAmount": {
    "value": 123.56,
    "currency": "USD"
  },
  "totalPostedAmount": {
    "value": 123.56,
    "currency": "USD"
  },
  "totalRemainingAmount": {
    "value": 123.56,
    "currency": "USD"
  },
  "travelAgency": {
    "href": "https://us.api.concursolutions.com/travelrequest/v4/travelagencies/2EC038D7C3CBBE4ABA0914425064D34F",
    "id": "2EC038D7C3CBBE4ABA0914425064D34F",
    "template": "https://us.api.concursolutions.com/travelrequest/v4/travelagencies/{id}"
  },
  "operations": [
    {
      "rel": "recall",
      "href": "https://us.api.concursolutions.com/travelrequest/v4/requests/053A479B3C9DD847B02A203C657AE26B/recall"
    },
    {
      "rel": "cancel",
      "href": "https://us.api.concursolutions.com/travelrequest/v4/requests/053A479B3C9DD847B02A203C657AE26B/cancel"
    }
  ]
}

Travel Request v4 - Getting Started

Concur Request automates the spend request and approval process for both travel and everyday expenses, giving you the data you need to accurately track and better control spending. By increasing visibility into planned expenses and up-to-date budget data, you can make strategic spending decisions before any spending actually occurs. The Request API provides many possibilities, particularly Requests creation and transition into the approval workflow.

Version 4.0 of Request API works only with the new Authentication API.

Getting Started

Overview

The Request v4 API exposes five different resources:

Resource Description
Request You can read, create, update or delete a Request and get the list of existing Requests.
Workflow You can perform action in the approval workflow of a Request (submit, approve, cancel...)
Expected Expense You can read, create, update or delete an expected expense, and get the list of expected Expenses for a specific Request.
Request Policy You can get the list of existing Request policies.
Travel Agency You can get the description of a Travel Agency office.

These resources are used to manage documents used for pre-spend authorizations within Concur Request.

Prior Versions

Process Flow

Process Flow for Request V4

Products and Editions

Scope Usage

Name Description Endpoint
travelrequest.write Read and write Requests GET, POST, PUT, DELETE

Dependencies

SAP Concur clients must purchase Concur Request in order to use this API. This API may require for some use cases to consume the following additional SAP Concur APIs:

Access Token Usage

This API supports both company level and user level access tokens.

Company Access Token

User Access Token

Travel Request v4 - HTTP Status Codes

HTTP Status Code Response Body Description
200 OK - Your GET request succeeded.
201 Created - Your POST request succeeded.
400 Bad Request badParam the request has bad parameter(s) {requestName} The name of the request doesn't have the expected format
- invalidJson invalid json structure An input JSON structure couldn't be parsed
- invalidDate error while parsing date value {dateValue} A date or datetime value couldn't be parsed
- invalidUuid for concur-correlationid {correlationId} The concur correlation id of the request is not a valid UUID
- invalidUuid {requestName} The name of the request doesn't have the expected format
- invalidLocation The location cannot be resolved, please provide either {iataCode} or {countryCode} and {cityName} Required location input is missing
- invalidLocation The location cannot be resolved, no location found for iataCode={iataCode} No location found matching the iataCode provided
- invalidLocation The location cannot be resolved, no city found for countryCode={countryCode}, cityName={cityName} and locationCode={locationCode} No location found matching the country code, city name and location code provided
- severalLocationsMatch The location cannot be resolved, multiple locations available for countryCode={countryCode} and cityName={cityName}. Please provide a locationCode from the possible matches Multiple locations found matching the country code and city name provided, location code is required.
- invalidPolicy invalid policy id
- listValidationError validation of list items failed
- missingRequiredField at least 1 required field has an empty value A request with no value on a mandatory field has been submitted
- blockingException at least 1 blocking exception A request with a blocking exception has been submitted
- multiLegNotAllowed cannot save a multi leg, multi-leg is not enabled for this entity The multi leg support is not allowed for the entity
- reportTemplateNotFound failed to retrieve report template The multi leg support is not allowed for the entity
- unsupportedParam the request has unsupported parameter(s) Some parameter(s) of the request are not supported
- missingRequiredParam the request is missing required parameter(s) The request is missing some required parameter(s)
- companyNotFound the company for this request has not been found The company for this request has not been found
- userNotFound user {id} not found The user Id for this request has not been found
- invalidUuid invalid {Uuid} for the userId The unique identifier for this userId is not valid
- - Limit must be less than or equal to 100 limit must be less than or equal to 100
- - Limit must be greater than or equal to 1 limit must be greater than or equal to 1
- - Limit must contains only digits Limit must contains only digits
401 Unauthorized invalidUser the request's user is invalid invalid or non existent authorization HTTP header
403 Forbidden permissionDenied permission denied User approving their own Request, or without approver/processor role
- requestStatusNotApproved the Request is not approved or canceled after approval
- userIsNotAllowed user is not allowed to access this resource
- requestStartDateInTheFuture expense report cannot be create from an approved Request before Request start
- publicApiNotAllowed entity is not allowed to access this resource
- publicApiNotAllowed this resource is not public
- CASH_ADVANCE_CANNOT_SUBMIT_AS_DELEGATE The cash advance cannot be submitted by the delegate.
- CASH_ADVANCE_CANNOT_APPROVE_OWN_CA You cannot approve your own cash advance.
404 Not Found notFound resource not found You tried to get a non-existing request
408 Request Timeout timeOut timeout has occurred
409 Conflict NO_APPROVER No approver was found. You must identify an approver before the request moves on to the next workflow step.
- NO_APPROVER_NOT_EDITABLE_STEP There are no approvers defined in your workflow. Contact your Expense administrator for assistance.
- NO_APPROVER_CHANGE_MY_INFO Missing the required approver for next workflow step. You may be able to select an approver; otherwise contact your Administrator for assistance.
- NO_AUTH_APPROVERS This request cannot be sent to the next approver. This workflow step must be approved by a specialised approver called an Authorised Approver. There are no Authorised Approvers defined. Please contact your Request administrator for assistance.
- REVIEW_APPROVAL_FLOW_APPROVER Review approvers in the workflow.
- APPROVER_CUM_REPORTOWNER You cannot send this request to this approver since this person created this request.
- APPROVER_CUM_REPORTOWNER_EDITABLE Your workflow is configured such that the request would come back to the request owner during some step. Please contact your Employee Administrator to change the approvers.
- INVALID_AUTH_APPROVER This request cannot proceed without an approver type of Authorised Approver. Select an approver who is an Authorised Approver before proceeding.
- CONFIG_INVALID_NEXT_STEP You must identify an approver before the request moves on to the next workflow step.
- STEP_EXIT_BLOCKING_BY_EXCEPTION One or more blocking exceptions are preventing approval submission. Resolve the exception before proceeding.
- CASH_ADVANCE_SUBMIT_GENERIC Cash Advance Status Change: Failure
- CASH_ADVANCE_SUBMIT_ALREADY_SUBMITTED The cash advance has already been submitted and cannot be submitted again.
- CASH_ADVANCE_CONFIG_INVALID_NEXT_STEP Cash Advance: You must identify an approver before the request moves on to the next workflow step
- CASH_ADVANCE_APPROVER_CUM_REPORTOWNER Cash Advance: You cannot send this request to this approver since this person created this request.
- CASH_ADVANCE_APPROVER_CUM_REPORTOWNER_IS_EDITABLE_BY Cash Advance: Your workflow is configured such that the claim would come back to the claim owner during some step. Please contact your Employee Administrator to change the approvers.
- CASH_ADVANCE_INVALID_AUTH_APPROVER Cash Advance: This request cannot be sent to the next approver. This workflow step must be approved by a specialised approver called an Authorised Approver. The selected approver is not an Authorised Approver. Select another approver.
- CASH_ADVANCE_NO_APPROVER Cash Advance: You must identify an approver before the request moves on to the next workflow step.
- CASH_ADVANCE_NO_APPROVER_CHANGE_MY_INFO Cash Advance: Missing the required approver for the next workflow step. Contact your Expense administrator for assistance.
- CASH_ADVANCE_NOT_AN_APPROVER Cash Advance: This request cannot be sent to the next approver because the selected approver is no longer authorised to approve requests. Please select another approver.
- CASH_ADVANCE_REVIEW_APPROVAL_FLOW_APPROVER Cash Advance: Review Approvers in the workflow.
500 Internal Server Error createReportError error while creating an expense report
- internalServerError internal server error
- associateReportError error while associating an expense report to a Request
503 Service Unavailable circuitBreaker Circuit Breaker is open, please try again on a different node The server node might be unavailable, be retrying the request you may reach a healthy node
- entityOffline Entity is offline, please try again later.
- CLIQBOOK_APPROVAL_FAILURE This request cannot be approved due to trip approval failure.
- CLIQBOOK_APPROVAL_RETRY This request cannot be approved immediately. Please try again later.
- CLIQBOOK_CANCEL_FAILURE This request cannot be cancelled due to trip cancel failure.

TRAVEL-RECEIPTS

Getting Started

Important: This API is currently in pre-release status and is only available to approved early access participants. The API is under development and might change before being generally released. To become an early access participant, contact your SAP Concur Representative.

The Travel Receipts service exposes receipt requests to inform E-Receipt partners which E-Receipts to send to SAP Concur and for which user. A partner can call the API and receive paged responses of receipt requests (a maximum of 25 receipt requests per page). When the next field is empty/null, the partner has reached the last page of receipt requests.

If the partner supplies a timestamp as a parameter, it is used as the start time for results. If not, the API retrieves the results from the last 24 hours.

Version

1.0

Regional Availability

US

https://us.api.concursolutions.com/travelreceipts/v1/receiptrequests

EMEA

https://emea.api.concursolutions.com/travelreceipts/v1/receiptrequests

Authentication

Partners must obtain an access token from the Authentication API.

The partner's access_token from the Authentication API response should then be used in the Authorization header of the Travel Receipts API calls.

Note: A token needs to be fetched for each datacenter, you cannot use the same token for US and EMEA.

Examples:

cURL:

curl -d "client_secret={YOUR SECRET}&client_id={YOUR CLIENT ID}&grant_type=client_credentials" https://us.api.concursolutions.com/oauth2/v0/token

HTTPie:

http -f POST https://us.api.concursolutions.com/oauth2/v0/token client_secret={YOUR SECRET} client_id={YOUR CLIENT ID} grant_type=client_credentials

Example Response

Important: This API is currently in pre-release status and is only available to approved early access participants. The API is under development and might change before being generally released. To become an early access participant, contact your SAP Concur Representative.

Below is a sample of receipt requests to show the response format a partner would receive from the API. The items are the receipt requests and the next links to the next page of results.

Receipt Request Response

Receipt Requests (Page 1)

Resp: {
    "items": [
    {
        "requestId": "905be7a3-882e-4bdf-8184-206908142aed",
        "vendor": "ZE",
        "confirmationNumber": "324186883",
        "firstName": "THOMAS",
        "lastName": "METGER",
        "segmentStartDate": "2018-01-30T14:40:00Z",
        "segmentEndDate": "2018-02-01T21:55:00Z",
        "requestDate": "2018-01-23T18:49:57.915931237Z"
    },
    {
        "requestId": "89eaff84-1cbe-4a2f-9048-5884117bd17e",
        "vendor": "ZE",
        "confirmationNumber": "335512084",
        "firstName": "CLYDE",
        "lastName": "DUNCAN",
        "segmentStartDate": "2018-01-23T15:30:00Z",
        "segmentEndDate": "2018-01-27T18:00:00Z",
        "requestDate": "2018-01-23T18:49:57.915933229Z"
    },
    {
        "requestId": "df1b2194-97b7-4c97-9c8a-fe5e42a6326b",
        "vendor": "ZE",
        "confirmationNumber": "443502429",
        "firstName": "SAM",
        "lastName": "SELIMAN",
        "segmentStartDate": "2018-03-16T18:15:00Z",
        "segmentEndDate": "2018-03-20T01:00:00Z",
        "requestDate": "2018-01-23T18:49:57.915935026Z"
    },
    {
        "requestId": "b338497d-6443-4c19-ab1d-105bf6acf01c",
        "vendor": "ZE",
        "confirmationNumber": "4652321537",
        "firstName": "WALTER",
        "lastName": "RICHARD",
        "segmentStartDate": "2018-01-22T14:00:00Z",
        "segmentEndDate": "2018-01-25T17:00:00Z",
        "requestDate": "2018-01-23T18:49:57.915936721Z"
    },
    {
        "requestId": "29a8925f-56a1-4a37-b3dc-fab2d1f85a1d",
        "vendor": "ZE",
        "confirmationNumber": "212291436",
        "firstName": "VAN",
        "lastName": "CLYDE",
        "segmentStartDate": "2018-01-22T16:00:00Z",
        "segmentEndDate": "2018-01-25T23:00:00Z",
        "requestDate": "2018-01-23T18:49:57.915938106Z"
    },
    {
        "requestId": "8b803a73-8dd2-43bf-8f35-8aa6d24f82c1",
        "vendor": "ZE",
        "confirmationNumber": "934514835",
        "firstName": "LYNN",
        "lastName": "CAREY",
        "segmentStartDate": "2018-01-23T18:45:00Z",
        "segmentEndDate": "2018-01-26T03:00:00Z",
        "requestDate": "2018-01-23T18:49:57.915939879Z"
    },
    {
        "requestId": "36653406-08f5-425f-b186-653c53fcf3b1",
        "vendor": "ZE",
        "confirmationNumber": "244689456",
        "firstName": "GEORGE",
        "lastName": "STOLLEY",
        "segmentStartDate": "2018-01-24T13:30:00Z",
        "segmentEndDate": "2018-01-25T13:30:00Z",
        "requestDate": "2018-01-23T18:49:57.915941244Z"
    },
    {
        "requestId": "44c2267e-8630-4ea7-a958-a598d2000611",
        "vendor": "ZE",
        "confirmationNumber": "530203526",
        "firstName": "CHRIS",
        "lastName": "GALLAGHER",
        "segmentStartDate": "2018-01-30T20:35:00Z",
        "segmentEndDate": "2018-02-03T13:15:00Z",
        "requestDate": "2018-01-23T18:49:57.915942604Z"
    },
    {
        "requestId": "7d6bbb2f-2862-44aa-9764-c779fae94fe9",
        "vendor": "ZE",
        "confirmationNumber": "455319127",
        "firstName": "STEVE",
        "lastName": "LOCK",
        "segmentStartDate": "2018-01-23T23:30:00Z",
        "segmentEndDate": "2018-01-26T23:30:00Z",
        "requestDate": "2018-01-23T18:49:57.915943946Z"
    },
    {
        "requestId": "ade1df9d-629f-4a99-86a2-2c6cc87221fb",
        "vendor": "ZE",
        "confirmationNumber": "163724658",
        "firstName": "TRACEY",
        "lastName": "CAMPBELL",
        "segmentStartDate": "2018-01-25T00:05:00Z",
        "segmentEndDate": "2018-01-26T18:40:00Z",
        "requestDate": "2018-01-23T18:49:57.915949116Z"
    },
    {
        "requestId": "787bd2ba-aaaf-4e04-ae85-1f05a3679101",
        "vendor": "ZE",
        "confirmationNumber": "245527331",
        "firstName": "SAMMY",
        "lastName": "STEVENS",
        "segmentStartDate": "2018-01-25T04:15:00Z",
        "segmentEndDate": "2018-01-26T02:25:00Z",
        "requestDate": "2018-01-23T18:49:57.915950543Z"
    },
    {
        "requestId": "ee74ace2-67bf-4af5-b64e-6695f7ea971d",
        "vendor": "ZE",
        "confirmationNumber": "132759455",
        "firstName": "DAVE",
        "lastName": "SCHULTZ",
        "segmentStartDate": "2018-02-03T02:07:00Z",
        "segmentEndDate": "2018-02-08T16:50:00Z",
        "requestDate": "2018-01-23T18:49:57.915951902Z"
    },
    {
        "requestId": "9d783dfc-6bcd-4391-b659-53b673c7eb23",
        "vendor": "ZE",
        "confirmationNumber": "537355772",
        "firstName": "GARY",
        "lastName": "BOTTIS",
        "segmentStartDate": "2018-01-23T02:25:00Z",
        "segmentEndDate": "2018-01-26T16:35:00Z",
        "requestDate": "2018-01-23T18:49:57.915953271Z"
    },
    {
        "requestId": "6cb48fad-0468-4f6a-8e68-6bc2dfbdda5f",
        "vendor": "ZE",
        "confirmationNumber": "553257291",
        "firstName": "NICOLE",
        "lastName": "ELKIDGE",
        "segmentStartDate": "2018-01-22T04:30:00Z",
        "segmentEndDate": "2018-01-26T21:00:00Z",
        "requestDate": "2018-01-23T18:49:57.915954617Z"
    },
    {
        "requestId": "539039fc-11ad-46d9-83f8-45260391caa9",
        "vendor": "ZE",
        "confirmationNumber": "304450523",
        "firstName": "NADIA",
        "lastName": "KHAN",
        "segmentStartDate": "2018-01-22T04:00:00Z",
        "segmentEndDate": "2018-01-26T16:00:00Z",
        "requestDate": "2018-01-23T18:49:57.915955955Z"
    },
    {
        "requestId": "c5198cd7-e87e-4f07-86fa-a712dcd49bbf",
        "vendor": "ZE",
        "confirmationNumber": "248124345",
        "firstName": "JAMIE",
        "lastName": "COTTIGAN",
        "segmentStartDate": "2018-01-29T23:00:00Z",
        "segmentEndDate": "2018-01-31T21:00:00Z",
        "requestDate": "2018-01-23T18:49:57.915957285Z"
    },
    {
        "requestId": "d567bfed-b6ca-40c0-a1ae-f5c5339e9258",
        "vendor": "ZE",
        "confirmationNumber": "322723456",
        "firstName": "SARAH",
        "lastName": "STANLEY",
        "segmentStartDate": "2018-06-06T19:14:00Z",
        "segmentEndDate": "2018-06-09T16:40:00Z",
        "requestDate": "2018-01-23T18:49:57.915958625Z"
    },
    {
        "requestId": "f9ae54c7-eb19-494b-a46c-bb5d76f17973",
        "vendor": "ZE",
        "confirmationNumber": "312876745",
        "firstName": "MELISSA",
        "lastName": "NIAYE",
        "segmentStartDate": "2018-01-26T22:50:00Z",
        "segmentEndDate": "2018-02-09T20:45:00Z",
        "requestDate": "2018-01-23T18:49:57.915961987Z"
    },
    {
        "requestId": "6378174d-d38b-4f9a-af85-8c3033efc491",
        "vendor": "ZE",
        "confirmationNumber": "313324743",
        "firstName": "SCOTTY",
        "lastName": "THOMPSON",
        "segmentStartDate": "2018-01-22T21:24:00Z",
        "segmentEndDate": "2018-01-26T13:15:00Z",
        "requestDate": "2018-01-23T18:49:57.915963318Z"
    },
    {
        "requestId": "aab3ea49-a899-4ecf-90b0-ed474408447e",
        "vendor": "ZE",
        "confirmationNumber": "313853757",
        "firstName": "MICHAEL",
        "lastName": "CARSON",
        "segmentStartDate": "2018-02-01T20:05:00Z",
        "segmentEndDate": "2018-02-02T23:25:00Z",
        "requestDate": "2018-01-23T18:49:57.915964654Z"
    },
    {
        "requestId": "99268619-f42a-4abd-ae44-698a37791a4e",
        "vendor": "ZE",
        "confirmationNumber": "4332095991",
        "firstName": "CECIL",
        "lastName": "LEE",
        "segmentStartDate": "2018-01-29T16:02:00Z",
        "segmentEndDate": "2018-02-01T16:40:00Z",
        "requestDate": "2018-01-23T18:49:57.915966004Z"
    },
    {
        "requestId": "18b124b8-7fa3-438b-85c6-57e16e5b3258",
        "vendor": "ZE",
        "confirmationNumber": "346384323",
        "firstName": "JOHN",
        "lastName": "FRANK",
        "segmentStartDate": "2018-04-25T16:00:00Z",
        "segmentEndDate": "2018-04-29T23:30:00Z",
        "requestDate": "2018-01-23T18:49:57.915967343Z"
    },
    {
        "requestId": "f80ee9ba-2d04-416e-9a96-ac7b282b38a9",
        "vendor": "ZE",
        "confirmationNumber": "407480677",
        "firstName": "STACEY",
        "lastName": "SCOTT",
        "segmentStartDate": "2018-02-05T18:00:00Z",
        "segmentEndDate": "2018-02-09T10:30:00Z",
        "requestDate": "2018-01-23T18:49:57.915968682Z"
    },
    {
        "requestId": "bb8da2e0-c7c2-454b-84bf-c3a2f9ed37fb",
        "vendor": "ZE",
        "confirmationNumber": "553338341",
        "firstName": "GEORGE",
        "lastName": "TESSER",
        "segmentStartDate": "2018-01-26T20:00:00Z",
        "segmentEndDate": "2018-01-28T20:00:00Z",
        "requestDate": "2018-01-23T18:49:57.9159701Z"
    },
    {
        "requestId": "a2903477-f4a8-4159-bf9a-4f42cea47ce1",
        "vendor": "ZE",
        "confirmationNumber": "530244855",
        "firstName": "ERICA",
        "lastName": "VANASSEY",
        "segmentStartDate": "2018-01-22T13:00:00Z",
        "segmentEndDate": "2018-01-23T00:00:00Z",
        "requestDate": "2018-01-23T18:49:57.915971485Z"
    }
    ],
    "next": "/v1/receiptrequests/1516561200/6443f257-03fe-5881-ac46-2e4865d944d3"
}

Receipt Requests (Page 2)

Resp: {
    "items": [
    {
        "requestId": "9ecf0b1c-d000-422a-907a-fd8370e5ca54",
        "vendor": "ZE",
        "confirmationNumber": "531758043",
        "firstName": "JENNIFER",
        "lastName": "SALINGER",
        "segmentStartDate": "2018-01-25T22:33:00Z",
        "segmentEndDate": "2018-01-26T23:30:00Z",
        "requestDate": "2018-01-23T18:49:58.194561445Z"
    },
    {
        "requestId": "f455b342-a3cd-4b4c-83fa-7413d169c0ed",
        "vendor": "ZE",
        "confirmationNumber": "53158372",
        "firstName": "CAROL",
        "lastName": "CHAN",
        "segmentStartDate": "2018-02-01T02:34:00Z",
        "segmentEndDate": "2018-02-02T02:00:00Z",
        "requestDate": "2018-01-23T18:49:58.194564178Z"
    },
    {
        "requestId": "b05c5b1d-abd4-49f5-9d5b-844845fbe82f",
        "vendor": "ZE",
        "confirmationNumber": "320572345",
        "firstName": "THOME",
        "lastName": "MOORE",
        "segmentStartDate": "2018-01-23T14:00:00Z",
        "segmentEndDate": "2018-01-26T22:00:00Z",
        "requestDate": "2018-01-23T18:49:58.194565985Z"
    },
    {
        "requestId": "42e17778-2a4d-4846-8cad-a3905ce19bed",
        "vendor": "ZE",
        "confirmationNumber": "533244823",
        "firstName": "KARIKA",
        "lastName": "BHONDA",
        "segmentStartDate": "2018-01-30T18:15:00Z",
        "segmentEndDate": "2018-02-02T14:00:00Z",
        "requestDate": "2018-01-23T18:49:58.194568541Z"
    },
    {
        "requestId": "7f9ec889-8870-4b55-a38c-f4a70a5023d3",
        "vendor": "ZE",
        "confirmationNumber": "530066134",
        "firstName": "BRUCE",
        "lastName": "ALLEN",
        "segmentStartDate": "2018-02-04T21:49:00Z",
        "segmentEndDate": "2018-02-10T01:09:00Z",
        "requestDate": "2018-01-23T18:49:58.19456995Z"
    },
    {
        "requestId": "33f23e5a-cce8-4cb5-9d3c-38b1b739a7a1",
        "vendor": "ZE",
        "confirmationNumber": "553489629",
        "firstName": "MICHAEL",
        "lastName": "GEORGE",
        "segmentStartDate": "2018-01-28T04:34:00Z",
        "segmentEndDate": "2018-02-04T18:45:00Z",
        "requestDate": "2018-01-23T18:49:58.194572246Z"
    },
    {
        "requestId": "042c5743-a628-4a8a-9875-c56f07239fc7",
        "vendor": "ZE",
        "confirmationNumber": "570148920",
        "firstName": "VINCENT",
        "lastName": "LEE",
        "segmentStartDate": "2018-01-21T23:00:00Z",
        "segmentEndDate": "2018-01-25T17:55:00Z",
        "requestDate": "2018-01-23T18:49:58.194573652Z"
    },
    {
        "requestId": "553fd318-4cce-4249-bf78-2cf2654251a7",
        "vendor": "ZE",
        "confirmationNumber": "531491044",
        "firstName": "STACY",
        "lastName": "BRITLEY",
        "segmentStartDate": "2018-02-05T04:16:00Z",
        "segmentEndDate": "2018-02-09T23:25:00Z",
        "requestDate": "2018-01-23T18:49:58.194575044Z"
    },
    {
        "requestId": "492e4253-0e82-45f5-9cc6-0d67ae5557c7",
        "vendor": "ZE",
        "confirmationNumber": "323508328",
        "firstName": "DAVID F",
        "lastName": "SETTER",
        "segmentStartDate": "2018-01-22T23:00:00Z",
        "segmentEndDate": "2018-01-26T02:00:00Z",
        "requestDate": "2018-01-23T18:49:58.194576479Z"
    },
    {
        "requestId": "48ea6ec0-e9ab-45b0-847f-e2b0b67cb594",
        "vendor": "ZE",
        "confirmationNumber": "323311322",
        "firstName": "KENT",
        "lastName": "CLARKE",
        "segmentStartDate": "2018-01-22T17:00:00Z",
        "segmentEndDate": "2018-01-26T11:00:00Z",
        "requestDate": "2018-01-23T18:49:58.194578761Z"
    },
    {
        "requestId": "c56f954a-855a-4260-a6ff-21b14cca1f8f",
        "vendor": "ZE",
        "confirmationNumber": "530520555",
        "firstName": "WILLIAM K",
        "lastName": "MASS",
        "segmentStartDate": "2018-02-22T14:00:00Z",
        "segmentEndDate": "2018-02-25T23:00:00Z",
        "requestDate": "2018-01-23T18:49:58.194580174Z"
    },
    {
        "requestId": "162dcae7-ee6d-483e-bd04-af59008d437d",
        "vendor": "ZE",
        "confirmationNumber": "5332461523",
        "firstName": "KUMAR",
        "lastName": "QUASBY",
        "segmentStartDate": "2018-01-30T20:03:00Z",
        "segmentEndDate": "2018-02-09T14:00:00Z",
        "requestDate": "2018-01-23T18:49:58.194581545Z"
    },
    {
        "requestId": "b502e51a-ef74-4fdd-96d1-bac9ac35bccb",
        "vendor": "ZE",
        "confirmationNumber": "532550992",
        "firstName": "JOSEPH",
        "lastName": "STICK",
        "segmentStartDate": "2018-03-30T03:45:00Z",
        "segmentEndDate": "2018-04-01T20:30:00Z",
        "requestDate": "2018-01-23T18:49:58.194582899Z"
    },
    {
        "requestId": "624ffcfa-dc88-4fe0-b7bb-efdbecd9c5bb",
        "vendor": "ZE",
        "confirmationNumber": "483591442",
        "firstName": "BETH ANN",
        "lastName": "MCFADDEN",
        "segmentStartDate": "2018-01-23T21:15:00Z",
        "segmentEndDate": "2018-01-25T21:15:00Z",
        "requestDate": "2018-01-23T18:49:58.194584223Z"
    },
    {
        "requestId": "f3306920-9229-4402-86a8-15fbee176fcf",
        "vendor": "ZE",
        "confirmationNumber": "533179846",
        "firstName": "KIMBERLY J",
        "lastName": "YAMASAKI",
        "segmentStartDate": "2018-01-21T22:00:00Z",
        "segmentEndDate": "2018-01-25T20:00:00Z",
        "requestDate": "2018-01-23T18:49:58.194585553Z"
    },
    {
        "requestId": "668fb7a9-3c6f-4750-acc1-e45235c2cd98",
        "vendor": "ZE",
        "confirmationNumber": "416150344",
        "firstName": "STEPHEN",
        "lastName": "BUCK",
        "segmentStartDate": "2018-01-22T18:00:00Z",
        "segmentEndDate": "2018-02-26T18:00:00Z",
        "requestDate": "2018-01-23T18:49:58.194586873Z"
    },
    {
        "requestId": "d5f8f682-395c-4ac5-afd9-ddd33f331f38",
        "vendor": "ZE",
        "confirmationNumber": "3290203462",
        "firstName": "SASHA",
        "lastName": "MALONE",
        "segmentStartDate": "2018-01-23T17:00:00Z",
        "segmentEndDate": "2018-01-26T17:00:00Z",
        "requestDate": "2018-01-23T18:49:58.194588192Z"
    },
    {
        "requestId": "c92a58c1-1008-4b67-afa9-5db14ce37a7d",
        "vendor": "ZE",
        "confirmationNumber": "353272082",
        "firstName": "ERIC",
        "lastName": "ZELMET",
        "segmentStartDate": "2018-01-22T04:00:00Z",
        "segmentEndDate": "2018-01-23T04:00:00Z",
        "requestDate": "2018-01-23T18:49:58.19459122Z"
    },
    {
        "requestId": "5372a3ed-f0d0-423a-80a6-121c7c4b40d1",
        "vendor": "ZE",
        "confirmationNumber": "533211431",
        "firstName": "YUNG",
        "lastName": "LIU",
        "segmentStartDate": "2018-03-07T18:12:00Z",
        "segmentEndDate": "2018-03-11T05:09:00Z",
        "requestDate": "2018-01-23T18:49:58.194592576Z"
    },
    {
        "requestId": "a8659cc9-2cea-42b2-95a0-60ce9c3d3ff7",
        "vendor": "ZE",
        "confirmationNumber": "530001832",
        "firstName": "SHANE",
        "lastName": "VANDIGRAFF",
        "segmentStartDate": "2018-01-29T18:23:00Z",
        "segmentEndDate": "2018-02-02T21:00:00Z",
        "requestDate": "2018-01-23T18:49:58.194593904Z"
    },
    {
        "requestId": "5a30d47f-d0bd-491c-a624-5d8f6c7ec3fb",
        "vendor": "ZE",
        "confirmationNumber": "532808260",
        "firstName": "SEAN F",
        "lastName": "SMITH",
        "segmentStartDate": "2018-01-22T17:00:00Z",
        "segmentEndDate": "2018-01-29T17:00:00Z",
        "requestDate": "2018-01-23T18:49:58.194595236Z"
    },
    {
        "requestId": "b8704c41-abc5-4f12-9d6f-f0820741f558",
        "vendor": "ZE",
        "confirmationNumber": "532593796",
        "firstName": "TROY P",
        "lastName": "DENOIT",
        "segmentStartDate": "2018-02-12T14:49:00Z",
        "segmentEndDate": "2018-02-16T20:40:00Z",
        "requestDate": "2018-01-23T18:49:58.194596581Z"
    },
    {
        "requestId": "1d593afb-e486-4b15-9188-60f9e6228c62",
        "vendor": "ZE",
        "confirmationNumber": "531745217",
        "firstName": "ROSS M",
        "lastName": "CLYDE",
        "segmentStartDate": "2018-02-05T13:45:00Z",
        "segmentEndDate": "2018-02-07T22:40:00Z",
        "requestDate": "2018-01-23T18:49:58.194597916Z"
    },
    {
        "requestId": "42183276-8691-4ee2-b243-3a87f0035cfc",
        "vendor": "ZE",
        "confirmationNumber": "319920342",
        "firstName": "KEVIN",
        "lastName": "HERNANDEZ",
        "segmentStartDate": "2018-01-22T03:02:00Z",
        "segmentEndDate": "2018-01-26T00:00:00Z",
        "requestDate": "2018-01-23T18:49:58.194599228Z"
    },
    {
        "requestId": "fb05fe58-ebe7-4f32-a844-a6a468bbcff0",
        "vendor": "ZE",
        "confirmationNumber": "322384229",
        "firstName": "WILLIAM",
        "lastName": "BOYESE",
        "segmentStartDate": "2018-01-22T15:45:00Z",
        "segmentEndDate": "2018-01-22T18:30:00Z",
        "requestDate": "2018-01-23T18:49:58.1946006Z"
    }
    ],
    "next": ""
}

Travel Receipts v1

Important: This API is currently in pre-release status and is only available to approved early access participants. The API is under development and might change before being generally released. To become an early access participant, contact your SAP Concur Representative.

The Travel Receipts service offers one endpoint for retrieving receipt requests.

The Travel Receipts service exposes receipt requests to inform e-receipt partners which e-receipts to send to SAP Concur and for which user.

If the partner supplies a timestamp, it is used as the start time for results. If not, the API retrieves the results from the last 24 hours.

Limitations: This API is not available in Implementation environments. This API is only available in the North American and EMEA Data Centers. This API is only available to SAP Concur e-receipt partners.

Products and Editions

Scope Usage

Name Description Endpoint
travel.receipts.read Retrieves a travel receipt. GET

Dependencies

None.

Access Token Usage

This API supports company level access tokens.

Retrieve Travel Receipt Requests

Retrieves all travel receipt requests for the partner.

The results of the API call are limited to a maximum of 25 receipt requests per page. The partner can navigate to the next page of results through the next field in the response. Each page keeps the same timestamp but will have a different key. The partner has reached the last page of results when next is null/empty.

Scopes

travel.receipts.read - Refer to Scope Usage for full details.

Request

URI

Template
https://{datacenterURI}/travelreceipts/v1/receiptrequests/{ts}/{key}
Parameters
Name Type Format Description
ts integer int64 Timestamp to specify a start time (if blank, defaults to last 24 hours).
key string uuid Current item key, populated from the previous response (from the next field in the response).

Headers

Payload

None.

Response

Status Codes

Headers

Payload

Example

{
  "items":[
  {
    "requestId":"12e1234e-3fa2-11e9-b37e-6a1234b3ceb0",
    "vendor":"ZE",
    "confirmationNumber":"H1234567A1",
    "firstName":"PAT",
    "lastName":"DAVIS",
    "segmentStartDate":"2019-03-14T00:30:00Z",
    "segmentEndDate":"2019-03-14T18:00:00Z",
    "requestDate":"2019-03-05T23:58:09.540514416Z"
  },
  {
    "requestId":"34e1234e-3fa2-11e9-b37e-6a1234b3ceb0",
    "vendor":"ZE",
    "confirmationNumber":" H1234567A2",
    "firstName":"MIKE",
    "lastName":"PARKER",
    "segmentStartDate":"2019-03-14T20:30:00Z",
    "segmentEndDate":"2019-03-15T23:45:00Z",
    "requestDate":"2019-03-05T23:58:09.540515177Z"
  },
  {
    "requestId":"56e1234e-3fa2-11e9-b37e-6a1234b3ceb0",
    "vendor":"ZE",
    "confirmationNumber":" H1234567A3",
    "firstName":"CHRIS",
    "lastName":"MILLER",
    "segmentStartDate":"2019-03-19T17:35:00Z",
    "segmentEndDate":"2019-03-21T00:40:00Z",
    "requestDate":"2019-03-05T23:58:09.540515833Z"
  },
  {
    "requestId":"78e1234e-3fa2-11e9-b37e-6a1234b3ceb0",
    "vendor":"ZE",
    "confirmationNumber":" H1234567A4",
    "firstName":"JANE",
    "lastName":"DOE",
    "segmentStartDate":"2019-03-06T05:53:00Z",
    "segmentEndDate":"2019-03-07T21:45:00Z",
    "requestDate":"2019-03-05T23:58:09.540520756Z"
    }
  ],
  "next":"/v1/receiptrequests/1551744000/12e1234e-3fa2-11e9-b37e-6a1234b3ceb0"
}

Schema

Response

Name Type Format Description
items Array Receipt Request An array of Receipt Request items.
next string - Key for the next page of results.

Receipt Request

Name Type Format Description
confirmationNumber string - Confirmation number for the receipt request.
firstName string - First name of the guest for the receipt request.
lastName string - Last name of the guest for the receipt request.
requestDate date-time ISO 8601 Date of the receipt request.
requestId uuid - ID for the receipt request.
segmentEndDate date-time ISO 8601 End date for the receipt request segment.
segmentStartDate date-time ISO 8601 Start date for the receipt request segment.
vendor string - Vendor code for the receipt request.

TRAVEL

Travel Services

Overview

The Travel services consists of a set of APIs that provide programmatic access to travel data such as itineraries, travel profiles, travel requests, and travel loyalty program information. These APIs are categorized into three sets of web services:

Itinerary

The Concur Itinerary web service can be used to pro grammatically access travel data such as trips and bookings in the Concur travel system. The Concur Travel system uses this data to match and consolidate bookings it receives from disparate sources and put these into consolidated travelers’ itineraries, providing travelers a convenient way to view their trips in a single itinerary view. Travelers can view their itineraries through mobile applications or other services.

Travel Profile Web Service

The Travel Profile Web Service consists of a set of resources that provide travel profile functionality customized in specific ways for developers, travel suppliers, and travel management companies (TMCs). Depending on who is using this web service, it provides the ability to update travel loyalty information, and subscribe and unsubscribe to travel profile changes.

Travel requests

Concur Travel Request web service is designed to help businesses control expenses by requiring employees to obtain approval before incurring expenses. It provides the ability to view requests and update the workflow for travel requests.

Trip approval

The Trip Approval resource allows clients to approve or reject trips. Clients send the unique identifier for the trip, the approver email and the workflow action to be performed (either approve or reject).

Itinerary Web Service (TMC/Third-Party)

The SAP Concur Itinerary Web Service allows Travel Management Companies (TMC), SAP Concur clients, and third-party developers to view and create travel related events in the Concur Travel system. TMCs can post bookings for any travel type. This web service can also be used by SAP Concur clients and third-party developers to request trip information for SAP Concur users. The public Itinerary XSD can be found here. In addition, the GetList XSD can be found here.

GET List of Itineraries

Retrieves trip summaries for the traveler specified in the OAuth token. This endpoint can also be used to get details for trips for a different user or the whole company. This is most often done when a Travel Management Company needs to get a list of trips on behalf of a user or company. During the request, a user with one of the following user roles from the user's company must authenticate through OAuth: Web Services Administrator for Professional, or Can Administer for Standard.

The response for this function can be divided into pages for easier processing.

Parameters

Name Description
tripId The trip id
startDate={_date_} The URL-encoded start date (in Coordinated Universal Time, aka UTC) for the trip. Format: YYYY-MM-DD. If no query parameters are provided, the start date is set to today's date - 30 days. The request will only return trips that are ongoing during the provided dates, either starting on the date, or starting before the date and ongoing during the provided date.
endDate****={_date_} The URL-encoded UTC end date for the trip. Format: YYYY-MM-DD. If no query parameters are provided, the end date is set to today's date + 12 months. The request will only return trips that are ongoing during the provided dates, either ending on the date, or starting before the date and ongoing during the provided date.
createdAfterDate****={_date_} The URL-encoded UTC date for when the trip was created. The query string will return trips created on or after this date. Used with the createdBeforeDate for finding trips created during a date range. Format: YYYY-MM-DD.
createdBeforeDate****={_date_} The URL-encoded UTC date for when the trip was created. The query string will return trips created on or before this date. Used with the createdAfterDate for finding trips created during a date range. Format: YYYY-MM-DD.
lastModifiedDate****={_date_} The last modified UTC date of the trips and any their associated bookings. This query string will return only the trips where the trip or any of its associated bookings have a last modified date that is greater or equal to the supplied time. The provided date/time can be anytime between now and the first date of trip creation in the database. The format is either the date or the date and time combined.
bookingType={_type_} The trip includes at least one booking of this type. Format: Air, Car, Dining, Hotel, Parking, Rail, or Ride
userid_type=login&userid_value=_{loginID}_ The loginID is the user's SAP Concur login ID. The userid_value of ALL can be sent to get trip summaries for all users at the company. The userid_type and userid_value parameters can only be used if the OAuth consumer has one of the user roles listed above.
includeMetadata=true&ItemsPerPage={_number_}&Page={_number_} The includeMetadata query parameter combined with the ItemsPerPage and Page query parameters will cause the response to be divided into pages. The response will be wrapped in a ConcurResponse parent element, with both the response details and the paging metadata included. The details of the response are here. If the ItemsPerPage query parameter is not sent, the response will default to 200 if the Page query parameter is sent, or 1000 if the Page query parameter is not set. If the Page query parameter is not sent, the response will default to page 1.
includeVirtualTrip=_1_ Virtual trips are segments booked offline through the Travel Request product. Set the includeVirtualTrip query parameter to 1 to include those trips in the list.
includeCanceledTrips=_{true/false}_ The includeCanceledTrips query parameter will cause the request to also return trips with a status of Canceled. When this query parameter is set to true, the response will include the TripStatus element.

Examples:

To get itinerary list for the entire company (OAuth consumer must have Admin user role):
https://www.concursolutions.com/api/travel/trip/v1.1/?startDate={startdate}&endDate={enddate}&_createdAfterDate={_date}&createdBeforeDate={date}&lastModifiedDate={date}&bookingType={type}&userid_type=login&userid_value=ALL

To get itinerary list for a single user (the OAuth consumer):
https://www.concursolutions.com/api/travel/trip/v1.1/?startDate={startdate}&endDate={enddate}&_createdAfterDate={_date}&createdBeforeDate={date}&lastModifiedDate={date}&bookingType={type}

To get itinerary list for a single user (other than the OAuth consumer):
https://www.concursolutions.com/api/travel/trip/v1.1/?startDate={startdate}&endDate={enddate}&_createdAfterDate={_date}&createdBeforeDate={date}&lastModifiedDate={date}&bookingType={type}&userid_type=login_id&userid_value={loginID}

XML Example Request by Start and End Date

GET /api/travel/trip/v1.1/?startDate=2012%2F02%2F01&endDate=2013%2F12%2F31 HTTP/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
...

XML Example Request by Booking Type and Start Date

GET /api/travel/trip/v1.1/?startDate=2012%2F02%2F01&bookingType=Air HTTP/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
...

XML Example Request by Created Date

GET /api/travel/trip/v1.1/?createdAfterDate=2012%2F02%2F01 HTTP/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}

XML Example Request with Paging

GET /api/travel/trip/v1.1/?createdAfterDate=2012%2F02%2F01&includeMetadata=true&ItemsPerPage=2&Page=1 HTTP/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}

Get List of Itineraries Response

This request will return an ItineraryInfoList parent element with an ItineraryInfo child element for each trip summary for the specified traveler. Each ItineraryInfo element has the following child elements:

Name Description
TripId Encrypted trip identifier value.
TripName Name of the trip
TripStatus The status of the trip. This element only appears if the includeCanceledTrips query parameter is used in the request.
StartDateLocal The start date of the trip in the starting location's timezone. Format: YYYY-MM-DDThh:mm:ss.
EndDateLocal The end date of the trip in the ending location's timezone. Format: YYYY-MM-DDThh:mm:ss.
UserLoginId The user's login to SAP Concur. Only appears when the OAuth consumer has one of the specified admin roles.
DateModifiedUtc The UTC date that this trip was last modified. Format: YYYY-MM-DDThh:mm:ss.
id Trip ID URI with encrypted ID.

Paging

If the includeMetadata and ItemsPerPage query parameters are included in the request, the response will include a ConnectResponse parent element with the following elements:

Name Description
Data This parent element contains the response as detailed above.
Metadata This parent element contains the Paging elements.

Paging Elements

The parent element of the paging information. Contains the following child elements:

Name Description
TotalPages The total number of pages the query returned.
TotalItems The total number of itineraries the query returned.
CurrentPage The page number for the set of results in the current response.
ItemsPerPage The number of items set to display per page.
PreviousPageURL The URI to the previous page of results. This element will be empty when there are no previous pages.
NextPageURL The URI to the next set of results. This element will be empty when there are no next pages.

XML Example of Successful Response

HTTP/1.1 200 OK
Content-Type: application/xml
...

<?xml version="1.0" encoding="utf-8"?>
<ItineraryInfoList xmlns="http://www.concursolutions.com/api/travel/trip/2010/06" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <ItineraryInfo>
        <TripId>naIzQJ0y2DBWjCIQOb2SHTsozwBsHDkdP</TripId>
        <TripName>Trip from Baltimore to New York</TripName>
        <StartDateLocal>2012-02-15T09:00:00</StartDateLocal>
        <EndDateLocal>2012-02-21T17:30:00</EndDateLocal>
        <UserLoginId>cm@example.com</UserLoginId>
        <DateModifiedUtc>2012-02-14T17:13:07</DateModifiedUtc>
        <id>https://www.concursolutions.com/api/travel/trip/v1.1/naIzQJ0y2DBWjCIQOb2SHTsozwBsHDkdP</id>
    </ItineraryInfo>
    <ItineraryInfo>
        <TripId>I2uwiJJw8r7Owl3IWlSie9WIelxhAhwiL</TripId>
        <TripName>Trip from Baltimore to Seattle</TripName>
        <StartDateLocal>2012-03-26T09:00:00</StartDateLocal>
        <EndDateLocal>2012-03-29T17:30:00</EndDateLocal>
        <DateModifiedUtc>2012-03-24T19:00:00</DateModifiedUtc>
        <UserLoginId>cm@example.com</UserLoginId>
        <id>https://www.concursolutions.com/api/travel/trip/v1.1/I2uwiJJw8r7Owl3IWlSie9WIelxhAhwiL</id>
    </ItineraryInfo>
</ItineraryInfoList>

XML Example of Successful Response with Paging

HTTP/1.1 200 OK
Content-Type: application/xml
...

<ConnectResponse>
    <Metadata>
        <Paging>
            <TotalPages>38</TotalPages>
            <TotalItems>187</TotalItems>
            <CurrentPage>2</CurrentPage>
            <ItemsPerPage>2</ItemsPerPage>
            <PreviousPageURL>https://www.concursolutions.com/api/travel/trip/v1.1/?createdAfterDate=2012%2F02%2F01&amp;itemsPerPage=5&amp;page=3&amp;includeMetaData=true</PreviousPageURL>
            <NextPageURL>https://www.concursolutions.com/api/travel/trip/v1.1/?createdAfterDate=2012%2F02%2F01&amp;itemsPerPage=5&amp;page=1&amp;includeMetaData=true</NextPageURL>
        </Paging>
    </Metadata>
    <Data>
        <ItineraryInfoList xmlns="http://www.concursolutions.com/api/travel/trip/2010/06" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
            <ItineraryInfo>
                <TripId>naIzQJ0y2DBWjCIQOb2SHTsozwBsHDkdP</TripId>
                <TripName>Trip from Baltimore to New York</TripName>
                <StartDateLocal>2012-02-15T09:00:00</StartDateLocal>
                <EndDateLocal>2012-02-21T17:30:00</EndDateLocal>
                <UserLoginId>cm@example.com</UserLoginId>
                <DateModifiedUtc>2012-02-14T17:13:07</DateModifiedUtc>
                <id>https://www.concursolutions.com/api/travel/trip/v1.1/naIzQJ0y2DBWjCIQOb2SHTsozwBsHDkdP</id>
            </ItineraryInfo>
            <ItineraryInfo>
                <TripId>I2uwiJJw8r7Owl3IWlSie9WIelxhAhwiL</TripId>
                <TripName>Trip from Baltimore to Seattle</TripName>
                <StartDateLocal>2012-03-26T09:00:00</StartDateLocal>
                <EndDateLocal>2012-03-29T17:30:00</EndDateLocal>
                <DateModifiedUtc>2012-03-24T19:00:00</DateModifiedUtc>
                <UserLoginId>cm@example.com</UserLoginId>
                <id>https://www.concursolutions.com/api/travel/trip/v1.1/I2uwiJJw8r7Owl3IWlSie9WIelxhAhwiL</id>
            </ItineraryInfo>
        </ItineraryInfoList>
    </Data>
</ConnectResponse>

GET Itinerary Details

Retrieves the details for the specified trip. By default, the OAuth consumer should be the owner of the trip. This endpoint can also be used to get details for trips that the OAuth consumer does not own. This is most often done when a Travel Management Company needs to get trip details on behalf of a user. The TMC must be registered with SAP Concur and have a SAP Concur account that has one of the following user roles: Web Services Administrator for Professional, or Can Administer for Standard.

The returned elements will vary based on the following conditions:

This documentation contains the full set of possible elements that can be returned. No itinerary can contain all of the possible elements, so the response will always be a subset of the possible returned values.

Parameters

Name Description
{_tripId_} Required. The identifier for the desired trip.
userid_type=login&userid_value=_{loginID}_ The loginID is the user's SAP Concur login ID. The userid_value of ALL can be sent to get trip summaries for all users at the company. The userid_type and userid_value parameters can only be used if the OAuth consumer has one of the user roles listed above.
systemFormat=_{format}_ The systemFormat query parameter can be used to specify that the response is formatted for a different system. The supported value is Tripit.

Get Itinerary Details Response

This request will return an Itinerary parent element with a subset of the following child elements:

Parameters

Name Description
BookedByFirstName The first name of the person who booked the trip.
BookedByLastName The last name of the person who booked the trip.
BookedVia The booking method for the trip.
CancelComments The comments provided if the itinerary is cancelled. Maximum length: 256 characters.
Comments Optional comments. Maximum length: 512 characters.
DateBookedLocal The date the trip was booked, in the local time of the booking location. Format: YYYY-MM-DDThh:mm:ss
DateCreatedUtc The date that this trip was created, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateModifiedUtc The date that this trip was last modified, in UTC. Format: YYYY-MM-DDThh:mm:ss
Description The trip description. Maximum length: 512 characters.
EndDateLocal The end date of the trip in the ending location's timezone. Format: YYYY-MM-DDThh:mm:ss
EndDateUtc The end date of the trip, in UTC. Format: YYYY-MM-DDThh:mm:ss
IsPersonal Whether the trip is a Business or Leisure trip. Format: true/false.
ProjectName The associated project name for the trip. Maximum length: 255 characters.
StartDateLocal The start date of the trip in the starting location's timezone. Format: YYYY-MM-DDThh:mm:ss
StartDateUtc The start date of the trip, in UTC. Format: YYYY-MM-DDThh:mm:ss
TripName Name of the trip. Maximum length: 255 characters.
Bookings This parent element will contain a Booking child element for each booking associated with this itinerary. Refer to the Booking Child Elements table.
RuleViolations The list of rule violations associated with the itinerary. This parent element contains a RuleViolation child element for each associated rule violation. Refer to the Public Itinerary XSD for more information.
Status The status of the itinerary. One of the following: 0 = Confirmed; 1 = Ticketed by agent; 2 = Canceled

Booking Child Elements

Name Description
BookingSource The name of the booking source for this booking. A booking source is a textual name the system uses to track where a booking took place.
DateBookedLocal The date the booking was created, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss
DateCreatedUtc The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateModifiedUtc The date the booking was last modified, in UTC. Format: YYYY-MM-DDThh:mm:ss
FormOfPaymentName The name of the form of payment for the booking.
FormOfPaymentType The type of the form of payment.
PassengerCount The number of passengers included in the booking.
RecordLocator Record locator for this booking. This is often six alphanumeric characters but can have other formats depending on the booking source.
RetrievedDateUtc The date the booking was last accessed, in UTC. Format: YYYY-MM-DDThh:mm:ss
TicketMailingAddress The mailing address for the booked ticket, if any.
TicketPickupLocation The pickup location for the booked ticket, if any.
TicketPickupNumber The confirmation number to pick up the booked ticket, if any.
AirfareQuotes List of stored airfare quotes. This parent element has a Quote child element for each airfare quote. The Quote parent element contains Airfare Quotes Child Elements
AirlineTickets List of Airline Tickets. This parent element contains Airline Tickets Child Elements
Charges The charges for the booking.
MiscChargeOrders This parent element has a MiscellaneousChargeOrder child element for each included miscellaneous charge. The MiscellaneousChargeOrder parent element contains Miscellaneous Charge Order Child Elements
Passengers This parent element has a Passenger child element for each included passenger. Refer to the Passenger Child Elements
PassPrograms This parent element has Pass Program child elements for each pass program associated with the booking.
PhoneNumbers This parent element has Phone Number Data child elements for each phone number associated with the booking.
RailPayments This parent element has Rail Payment Child Elements
Segments This parent element will contain at least one of the following child elements: Air, Car, Hotel, Dining, Ride, Rail, Parking.
Delivery The method used to deliver this booking. Refer to the Delivery Method Child Elements
WaitListSegments Information will appear in this element if the segment is on a waiting list.
Warnings The warnings associated with the booking.
WebAddresses List of web addresses. This parent element includes Web Address Data child elements for each associated web address.
BookingReferrer BookingReferrer is used only in specific source tracking scenarios when there is a need to distinguish between bookings with the same BookingSources coming through different flows. Do not populate without coordinating with your technical contact. The supported values are: Concur Travel, Sign-in with SAP Concur, Supplier Mobile, Supplier Web.

Airfare Quotes Child Elements

Name Description
BaseFare The base fare of the booking quote.
BaseFareCurrency The 3-letter ISO 4217 currency code for the booking quote.
BaseFareNuc The base fare in NUC.
BaseFareNucCurrency The 3-letter ISO 4217 currency code for the base fare in NUC.
DateCreatedUtc The date the quote was created, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateModifiedUtc The date the quote was last modified, in UTC. Format: YYYY-MM-DDThh:mm:ss
Endorsements Notes from the airline if it endorses the ticket as acceptable on a different airline.
IssueByDate The date the quote must be issued by. Format: YYYY-MM-DDThh:mm:ss
TotalFare The total price of the booking.
TotalFareCurrency The 3-letter ISO 4217 currency code for the total fare.
AirlineCharges The charges applied by the airline. This parent element contains a Fixed child element for each fixed charge from the airline.
Taxes The taxed applied to this airline ticket.

Airline Tickets Child Elements

Name Description
ManualAirlineTicket The manual airline ticket for the booking.
AirlineTicket The airline ticket for the booking.
AirlineAdjustment Any adjustment made to the booking.

Miscellaneous Charge Order Child Elements

Name Description
DateCreatedUtc The date the charge order was created, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateModifiedUtc The date the charge order was last modified, in UTC. Format: YYYY-MM-DDThh:mm:ss
IssueDate The date the charge order was issued. Format: YYYY-MM-DDThh:mm:ss
PlatingCarrierNumericCode Part of the ticket number that indicates the airline code. This is a three digit number. For example: 001=American, 005=Continental, 006=Delta, 012=Northwest
PlatingControlNumber Part of the ticket number that indicates the ticket control number. Format: Ten digit number.
TotalAmount The total amount of charge orders for the ticket.
TotalAmountCurrency The 3-letter ISO 4217 currency code for the total charge order amount.

Pass Programs Child Elements

Name Description
Amount The program amount.
Name The program name.
Type The program type.
UserFirstName The first name of the passenger.
UserLastName The last name of the passenger.

Phone Number Data Child Elements

Name Description
PassengerRPH Indicates the passenger to whom this phone number belongs.
PhoneNumber The passenger's phone number.
Type The type of phone number.
Description The description for the phone number.

Rail Payments Child Elements

Name Description
RailPayment The payment information for a rail booking.
RailAdjustment The amount adjusted for a rail booking. Refer to the Public Itinerary XSD for more information.

Delivery Method Child Elements

Name Description
LocationAdditionalDetails Additional information about the delivery location.
AddressLine1 The delivery address.
AddressLine2 The delivery address.
City The delivery address.
Country The delivery address.
LocationDesc Description of the delivery location.
Email The delivery email contact.
Latitude The delivery address.
Longitude The delivery address.
LocationName The name of the delivery location.
PhoneNumber The phone number of the delivery contact.
ReferenceNumber The reference number for the delivery.
State The delivery address.
Type The type of delivery address.
Zip The delivery address.

Web Address Data Child Elements

Name Description
PassengerRPH Indicates the passenger to whom this web address belongs.
WebAddress Web address. Format: email address or URL. Maximum length: 250 characters.
Format Format of the web address. Format: E=Email, U=URL, I=IM
Type Type code for web address. Format: TKT, RES, BUS
Description Free text describing the web address. Maximum length: 50 characters.

Passenger Child Elements

Name Description
FirstNameNumber The number of characters in the passenger's first name.
LastNameNumber The number of characters in the passenger's last name.
NameFirst The passenger's first name.
NameLast The passenger's last name.
NameMiddle The passenger's middle name.
NamePrefix The passenger's name prefix.
NameRemark Additional details about the passenger's name.
NameSuffix The passenger's name suffix.
NameTitle The passenger's name title.
TextName The user's full name.
FrequentTravelerProgram The passenger's loyalty program identifier. This parent element contains the FrequentFlyer and RailProgram child elements.
FrequentFlyer The passenger's frequent flyer program details. This parent element has Frequent Flyer Child Elements
RailProgram The passenger's rail loyalty program details. This parent element has Rail Program Child Elements

Frequent Flyer Child Elements

Name Description
AirlineVendor The vendor of the frequent flyer program.
Description The program description.
DiscountProgramExpirationDate The date the discount program enrollment expires. Format: YYYY-MM-DDThh:mm:ss
DiscountProgramType The type of discount program.
FrequentFlyerNumber The passenger's identifier for the program.
ProgramVendor The program vendor.
Status The passenger's program status.
StatusExpirationDate The expiration date for the passenger's program status.

Rail Program Child Elements

Name Description
Description Description of the discount program.
DiscountProgramExpirationDate The date the discount program enrollment expires. Format: YYYY-MM-DDThh:mm:ss
DiscountProgramType The type of discount program.
ProgramNumber The passenger's identifier for the program.
ProgramVendor The program vendor.
Status The passenger's program status.
StatusExpirationDate The expiration date for the passenger's program status.

XML Example of Successful Response

HTTP/1.1 200 OK
Content-Type: application/xml
...

<?xml version="1.0" encoding="utf-8"?>
<Itinerary xmlns="http://www.concursolutions.com/api/travel/trip/2010/06">
    <id>https://www.concursolutions.com/api/travel/trip/v1.1/CNQR1234567890</id>
    <ItinLocator>CNQR1234567890</ItinLocator>
    <ClientLocator>KK-CNQ-1M1P6-5HJ</ClientLocator>
    <ItinSourceName>ConcurTravel</ItinSourceName>
    <TripName>Trip from Dallas to Seattle</TripName>
    <Comments />
    <StartDateLocal>2013-12-21T07:25:00</StartDateLocal>
    <EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
    <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
    <BookedVia>EveryGDS</BookedVia>
    <BookedByFirstName>Chris</BookedByFirstName>
    <BookedByLastName>Miller</BookedByLastName>
    <DateBookedLocal>2012-07-24T19:15:52</DateBookedLocal>
    <Bookings>
        <Booking>
            <Segments>
                <Car>
                    <Vendor>CQ</Vendor>
                    <Status>HK</Status>
                    <StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
                    <EndDateLocal>2013-12-24T12:00:00</EndDateLocal>
                    <ConfirmationNumber>F1672664579</ConfirmationNumber>
                    <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
                    <StartCityCode>SEA</StartCityCode>
                    <EndCityCode>SEA</EndCityCode>
                    <StartLocation>SEA</StartLocation>
                    <EndLocation>SEA</EndLocation>
                    <Class>E</Class>
                    <Body>C</Body>
                    <Transmission>M</Transmission>
                    <AirCondition>R</AirCondition>
                    <NumCars>1</NumCars>
                    <DiscountCode>346660</DiscountCode>
                    <DailyRate>44.0000</DailyRate>
                    <TotalRate>44.0000</TotalRate>
                    <RateType>D</RateType>
                    <Currency>USD</Currency>
                    <Charges>
                        <Fixed>
                            <Description>Dropoff Fee</Description>
                            <Currency>USD</Currency>
                            <Amount>0.0000</Amount>
                            <IsPrimary>false</IsPrimary>
                            <SemanticsCode>DROPOFFFEE</SemanticsCode>
                            <SemanticsVendorType>C</SemanticsVendorType>
                        </Fixed>
                        <RateWithAllowance>
                            <Currency>USD</Currency>
                            <Amount>44.0000</Amount>
                            <StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
                            <IsPrimary>true</IsPrimary>
                            <SemanticsCode>DAYS</SemanticsCode>
                            <SemanticsVendorType>C</SemanticsVendorType>
                            <PerUnit>DAY</PerUnit>
                            <NumUnits>1.0000</NumUnits>
                            <AllowanceNumUnits>250.0000</AllowanceNumUnits>
                            <AllowanceAmount>0.2400</AllowanceAmount>
                            <AllowanceIsUnlimited>false</AllowanceIsUnlimited>
                        </RateWithAllowance>
                    </Charges>
                </Car>
            </Segments>
            <Passengers>
                <Passenger>
                    <NameFirst>Chris</NameFirst>
                    <NameLast>Miller</NameLast>
                </Passenger>
            </Passengers>
            <RecordLocator>C123456789</RecordLocator>
            <BookingSource>ConcurCars</BookingSource>
            <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
            <DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
            <ItinSourceName>TravelSupplier</ItinSourceName>
            <PassengerCount>1</PassengerCount>
        </Booking>
        <Booking>
            <Segments>
                <Hotel>
                    <Vendor>CQ</Vendor>
                    <Status>GK</Status>
                    <StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
                    <EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
                    <ConfirmationNumber>3364214265</ConfirmationNumber>
                    <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
                    <RateCode>LV4</RateCode>
                    <Name>CONCUR HOTEL</Name>
                    <HotelPropertyId>CONQ</HotelPropertyId>
                    <CheckinTime>00:00</CheckinTime>
                    <CheckoutTime>00:00</CheckoutTime>
                    <NumPersons>1</NumPersons>
                    <NumRooms>1</NumRooms>
                    <CancellationPolicy>Cxl 1 day prior to Arrival</CancellationPolicy>
                    <DailyRate>240.3500</DailyRate>
                    <Currency>USD</Currency>
                    <RoomDescription>1 KING BED ACCESSIBLE ROOM - K1RRC</RoomDescription>
                    <Charges>
                        <Rate>
                            <Currency>USD</Currency>
                            <Amount>240.3500</Amount>
                            <StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
                            <IsPrimary>false</IsPrimary>
                            <SemanticsCode>ROOMRATE</SemanticsCode>
                            <SemanticsVendorType>H</SemanticsVendorType>
                            <PerUnit>DAY</PerUnit>
                            <NumUnits>3.0000</NumUnits>
                        </Rate>
                    </Charges>
                </Hotel>
            </Segments>
            <Passengers>
                <Passenger>
                    <NameFirst>Chris</NameFirst>
                    <NameLast>Miller</NameLast>
                </Passenger>
            </Passengers>
            <RecordLocator>0987654321</RecordLocator>
            <BookingSource>ConcurHotel</BookingSource>
            <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
            <DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
            <OriginalItinLocator>33491211</OriginalItinLocator>
            <ItinSourceName>ConcurTravel</ItinSourceName>
            <PassengerCount>1</PassengerCount>
        </Booking>
    </Bookings>
</Itinerary>

XML Response in TripIt Format

<?xml version="1.0" encoding="utf-8"?>
<Response>
    <Trip>
        <id>73014481752</id>
        <relative_url>/api/travel/trip/v1.1/73014481752</relative_url>
        <start_date>2013-08-21</start_date>
        <end_date>2013-08-24</end_date>
        <display_name>Strategy Team meeting</display_name>
        <is_private>true</is_private>
    </Trip>
    <AirObject>
        <booking_site_conf_num>RL10001005</booking_site_conf_num>
        <booking_site_name>Concur Travel</booking_site_name>
        <booking_site_phone></booking_site_phone>
        <booking_site_url>https://www.concursolutions.com</booking_site_url>
        <record_locator>4294993825</record_locator>
        <supplier_conf_num>CN10001005</supplier_conf_num>
        <supplier_contact></supplier_contact>
        <supplier_email_address></supplier_email_address>
        <supplier_name></supplier_name>
        <supplier_phone></supplier_phone>
        <supplier_url></supplier_url>
        <is_purchased>1</is_purchased>
        <notes></notes>
        <restrictions></restrictions>
        <total_cost></total_cost>
        <Segment>
            <StartDateTime>
                <date>2013-08-21</date>
                <time>07:45:00</time>
            </StartDateTime>
            <EndDateTime>
                <date>2013-08-21</date>
                <time>13:03:00</time>
            </EndDateTime>
            <start_airport_code>PHX</start_airport_code>
            <start_gate>A11</start_gate>
            <start_terminal>4</start_terminal>
            <end_airport_code>ORD</end_airport_code>
            <end_gate>F8</end_gate>
            <end_terminal>2</end_terminal>
            <marketing_airline>US</marketing_airline>
            <marketing_flight_number>1</marketing_flight_number>
            <aircraft>320</aircraft>
            <duration></duration>
            <distance>1433</distance>
            <notes></notes>
            <seats></seats>
            <service_class>Economy</service_class>
            <stops>Nonstop</stops>
        </Segment>
        <Segment>
            <StartDateTime>
                <date>2013-08-24</date>
                <time>13:55:00</time>
            </StartDateTime>
            <EndDateTime>
                <date>2013-08-24</date>
                <time>16:58:00</time>
            </EndDateTime>
            <start_airport_code>ORD</start_airport_code>
            <start_gate></start_gate>
            <start_terminal></start_terminal>
            <end_airport_code>PHX</end_airport_code>
            <end_gate></end_gate>
            <end_terminal></end_terminal>
            <marketing_airline>US</marketing_airline>
            <marketing_flight_number>1728</marketing_flight_number>
            <aircraft>A320</aircraft>
            <duration></duration>
            <distance></distance>
            <notes></notes>
            <seats></seats>
            <service_class>Economy</service_class>
            <stops> stops</stops>
        </Segment>
        <Traveler>
            <first_name>William</first_name>
            <middle_name></middle_name>
            <last_name>Never</last_name>
            <frequent_traveler_num></frequent_traveler_num>
            <frequent_traveler_supplier></frequent_traveler_supplier>
            <ticket_num></ticket_num>
        </Traveler>
    </AirObject>
</Response>

POST Itinerary Details

Description

Creates a new trip or updates an existing trip. A new trip will be created if the trip dates span no existing trip and the request doesn't include a tripId. If a tripId is included in the URI it will update the specified trip. The full trip information is included in the update request, which replaces the existing trip.

This endpoint can be used to create trips for a user that is not the OAuth consumer. This is most often done when a travel supplier or Travel Management Company needs to create a trip on behalf of a user. The supplier or TMC must be registered with SAP Concur and have an SAP Concur account that has one of the following user roles: Web Services Administrator for Professional, or Can Administer for Standard.

Agency Proposals

Travel Management Companies for SAP Concur clients with the Agency Proposal feature of Travel Request can send proposed itineraries using the Itinerary web service. The TMC will indicate that the itinerary is a proposal using the TripStatus element. The request must also include the CustomAttributes element and its child elements.

Query Parameters - Required Supported Content Types
None application/xml

Query Parameters - Optional

Examples:
To post a new trip for the OAuth consumer:
https://www.concursolutions.com/api/travel/trip/v1.1

To update a trip for the OAuth consumer:
https://www.concursolutions.com/api/travel/trip/v1.1?tripId={_tripId_}

To post a trip for a user other than the OAuth consumer:
https://www.concursolutions.com/api/travel/trip/v1.1?userid_type=login_id&userid_value={_loginID_}

Request Headers - Required Request Headers - Optional
Authorization header with OAuth token for valid SAP Concur user. To post trips for users other than the OAuth consumer, the OAuth consumer must have one of the following user roles in SAP Concur: Company Administrator or Web Services Administrator for Professional, or Can Administer for Standard. None

Content Body

This function requires as its arguments an Itinerary parent element. The parent element contains the following child elements:

Required Elements

Element Description
TripName Name of the trip. Maximum length: 255 characters.
TripStatus The status of the itinerary. One of the following:
0 - Confirmed
1 - Ticketed
2 - Canceled
6 - Proposal
7 - Booked Proposal

Required Elements for Agency Proposal

Element Description
ClientLocator The unique identifier for the batch of proposals. All proposals in the batch should have the same value.
TravelRequestId The identifier for the travel request that the proposal is associated with.
CustomAttributes This parent element will contain CustomAttributes child element. The CustomAttributes child elements are detailed in the CustomAttributes Elements table.

CustomAttributes Elements - Required

DataType Name Data Supported Values Comment
Numeric ProposalBatchSize 1 to 3 The number of proposals in the batch. Maximum: 3
Numeric ProposalSequenceIndex 1 to 3 The index of the proposal in the batch of proposals.
Text AutoSelectProposal True, False If true, then the proposal will be selected accordingly and replace the segments previously entered by the user.
If False, then the proposal will be up to the user to decide which proposal s/he wants to manually select.
Text TicketIssued True, False Are the tickets for this proposal issued or not.
Text DisplayOnItinerary True The value for this element has to be 'True'.
N/A DisplayTitle N/A This element should be empty.
N/A ExternalId N/A This element should be empty.

Optional Elements

Element Description
BookedByFirstName First name of the trip owner.
BookedByLastName Last name of the trip owner.
Bookings This parent element will contain a Booking child element for each booking associated with this itinerary. The Booking child elements are detailed in the Booking Elements table.
CancelComments User supplied comments if the trip is cancelled. 256 Characters Maximum
Comments Comments on the itinerary. 512 Characters Maximum
DateBookedLocal The date the trip was booked, in the local time of the booking location. Format: YYYY-MM-DDThh:mm:ss
Description The trip description. Maximum length: 512 characters.
IsPersonal Whether the trip is a Business or Leisure trip.
ProjectName The associated project name for the trip. Maximum length: 255 characters.
RuleViolations The list of rule violations associated with the itinerary. This parent element contains a child element for each associated rule violation.

Booking Elements - Required

Element Description
BookingSource The name of the booking source for this booking. A booking source is a textual name the system uses to track where a booking took place. This could be a GDS, OTA, Vendor code for Supplier website, or Supplier Direct Connect API.
RecordLocator The unique identifier for the booking. Send the value for an existing booking to update an existing trip.

Booking Elements - Optional

Element Description
BookingOwner Indicates the tool that supplied the booking to Concur Travel.
Source Obsolete, supported for backward compatibility.
DateBookedLocal The date the booking was created, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss
FormOfPaymentName The name of the form of payment for the booking.
FormOfPaymentType The type of the form of payment.
TicketMailingAddress The mailing address for the booked ticket, if available.
TicketPickupLocation The pickup location for the booked ticket, if available.
TicketPickupNumber The confirmation number for the booked ticket, if available.
AirfareQuotes List of stored airfare quotes for this booking.
Airline Tickets List of airline tickets for this booking.
Charges List of charges for this booking.
MiscChargeOrders List of Miscellaneous AirCharges for this booking.
Passengers This parent element contains a Passenger child element for each booked passenger. The Passenger child element contains the following child elements:
NameFirst - The first name of the passenger.
NameLast (optional) - The last name of the passenger.
NameMiddle - The middle name of the passenger.
NamePrefix - The passenger's name prefix.
NameRemark - Additional details about the passenger's name.
NameSuffix - The passenger's name suffix.
NameTitle - The passenger's name title.
TextName - The user's full name as entered in the booking tool if different from the name in the database.
FrequentTravelerProgram - Passenger's loyalty programs.
PassPrograms List of Pass Programs for this booking.
PhoneNumbers List of Phone numbers associated with this booking.
RailPayments List of Rail payments associated with rail segments in this booking.
Segments This parent element will contain at least one of the following child elements: Air, Car, Hotel, Dining, Ride, Rail, Parking, Event.
Delivery The method this booking was delivered. 
WaitListSegments The segments that the traveler is waitlisted for this booking.
Warning The warnings associated with the booking.
WebAddresses List of web addresses such as emails, pickup URLs, etc. associated with this booking.
BookingReferrer BookingReferrer is used only in specific source tracking scenarios when there is a need to distinguish between bookings with the same BookingSources coming through different flows. Do not populate without coordinating with your technical contact. The supported values are: Concur Travel, Sign-in with SAP Concur, Supplier Mobile, Supplier Web

XML Example Request

POST /api/travel/trip/v1.1?userid_type=login_id&userid_value=cm@example.com HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
Content-Type: application/xml
...

<Itinerary xmlns="http://www.concursolutions.com/api/travel/trip/2010/06">
    <ClientLocator>KK-CNQ-1M1P6-5HJ</ClientLocator>
    <ItinSourceName>ConcurConnectAPI</ItinSourceName>
    <TripName>Trip from Dallas to Seattle</TripName>
    <Comments />
    <StartDateLocal>2013-12-21T07:25:00</StartDateLocal>
    <EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
    <BookedByFirstName>Chris</BookedByFirstName>
    <BookedByLastName>Miller</BookedByLastName>
    <Bookings>
        <Booking>
            <Segments>
                <Car>
                    <Vendor>CQ</Vendor>
                    <Status>HK</Status>
                    <StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
                    <EndDateLocal>2013-12-24T12:00:00</EndDateLocal>
                    <ConfirmationNumber>F1672664579</ConfirmationNumber>
                    <StartCityCode>SEA</StartCityCode>
                    <EndCityCode>SEA</EndCityCode>
                    <StartLocation>SEA</StartLocation>
                    <EndLocation>SEA</EndLocation>
                    <Class>E</Class>
                    <Body>C</Body>
                    <Transmission>M</Transmission>
                    <AirCondition>R</AirCondition>
                    <NumCars>1</NumCars>
                    <DiscountCode>346660</DiscountCode>
                    <DailyRate>44.0000</DailyRate>
                    <TotalRate>44.0000</TotalRate>
                    <RateType>D</RateType>
                    <Currency>USD</Currency>
                    <Charges>
                        <Fixed>
                            <Description>Dropoff Fee</Description>
                            <Currency>USD</Currency>
                            <Amount>0.0000</Amount>
                            <IsPrimary>false</IsPrimary>
                            <SemanticsCode>DROPOFFFEE</SemanticsCode>
                            <SemanticsVendorType>C</SemanticsVendorType>
                        </Fixed>
                        <RateWithAllowance>
                            <Currency>USD</Currency>
                            <Amount>44.0000</Amount>
                            <StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
                            <IsPrimary>true</IsPrimary>
                            <SemanticsCode>DAYS</SemanticsCode>
                            <SemanticsVendorType>C</SemanticsVendorType>
                            <PerUnit>DAY</PerUnit>
                            <NumUnits>1.0000</NumUnits>
                            <AllowanceNumUnits>250.0000</AllowanceNumUnits>
                            <AllowanceAmount>0.2400</AllowanceAmount>
                            <AllowanceIsUnlimited>false</AllowanceIsUnlimited>
                        </RateWithAllowance>
                    </Charges>
                </Car>
            </Segments>
            <Passengers>
                <Passenger>
                    <NameFirst>Chris</NameFirst>
                    <NameLast>Miller</NameLast>
                </Passenger>
            </Passengers>
            <RecordLocator>C123456789</RecordLocator>
            <BookingSource>TravelBookings.com</BookingSource>
            <DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
            <ItinSourceName>ConcurConnectAPI</ItinSourceName>
            <PassengerCount>1</PassengerCount>
        </Booking>
        <Booking>
            <Segments>
                <Hotel>
                    <Vendor>CQ</Vendor>
                    <Status>GK</Status>
                    <StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
                    <EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
                    <ConfirmationNumber>3364214265</ConfirmationNumber>
                    <RateCode>LV4</RateCode>
                    <Name>CONCUR HOTEL</Name>
                    <HotelPropertyId>CONQ</HotelPropertyId>
                    <CheckinTime>03:00 PM</CheckinTime>
                    <CheckoutTime>12:00 PM</CheckoutTime>
                    <NumPersons>1</NumPersons>
                    <NumRooms>1</NumRooms>
                    <CancellationPolicy>Cxl 1 day prior to Arrival</CancellationPolicy>
                    <DailyRate>240.3500</DailyRate>
                    <Currency>USD</Currency>
                    <RoomDescription>1 KING BED ACCESSIBLE ROOM - K1RRC</RoomDescription>
                    <Charges>
                        <Rate>
                            <Currency>USD</Currency>
                            <Amount>240.3500</Amount>
                            <StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
                            <IsPrimary>false</IsPrimary>
                            <SemanticsCode>ROOMRATE</SemanticsCode>
                            <SemanticsVendorType>H</SemanticsVendorType>
                            <PerUnit>DAY</PerUnit>
                            <NumUnits>3.0000</NumUnits>
                        </Rate>
                    </Charges>
                </Hotel>
            </Segments>
            <Passengers>
                <Passenger>
                    <NameFirst>Chris</NameFirst>
                    <NameLast>Miller</NameLast>
                </Passenger>
            </Passengers>
            <RecordLocator>0987654321</RecordLocator>
            <BookingSource>TravelBookings.com</BookingSource>
            <DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
            <OriginalItinLocator>33491211</OriginalItinLocator>
            <ItinSourceName>ConcurConnectAPI</ItinSourceName>
            <PassengerCount>1</PassengerCount>
        </Booking>
    </Bookings>
</Itinerary>

XML Example Request of Agency Proposal

POST https://www.concursolutions.com/api/travel/trip/v1.1?userid_type=login_id&userid_value=cm@example.com HTTPS/1.1
Authorization: OAuth {access token}
Content-Type: application/xml
...

<Itinerary xmlns="http://www.concursolutions.com/api/travel/trip/2010/06">
    <ClientLocator>KK-CNQ-1M1P6-5HJ</ClientLocator>
    <ItinSourceName>ConcurConnectAPI</ItinSourceName>
    <TripName>Trip from Dallas to Seattle</TripName>
    <Comments />
    <StartDateLocal>2013-12-21T07:25:00</StartDateLocal>
    <EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
    <BookedByFirstName>Chris</BookedByFirstName>
    <BookedByLastName>Miller</BookedByLastName>
    <TripStatus>7</TripStatus>
    <TravelRequestId>3339</TravelRequestId>
    <CustomAttributes>
        <CustomAttribute>
            <ExternalId />
            <DataType>Numeric</DataType>
            <Name>ProposalBatchSize</Name>
            <DisplayTitle />
            <Data>3</Data>
            <DisplayOnItinerary>true</DisplayOnItinerary>
        </CustomAttribute>
        <CustomAttribute>
            <ExternalId />
            <DataType>Numeric</DataType>
            <Name>ProposalSequenceIndex</Name>
            <DisplayTitle />
            <Data>1</Data>
            <DisplayOnItinerary>true</DisplayOnItinerary>
        </CustomAttribute>
    </CustomAttributes>
    <Bookings>
        <Booking>
            <Segments>
                <Car>
                    <Vendor>CQ</Vendor>
                    <Status>HK</Status>
                    <StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
                    <EndDateLocal>2013-12-24T12:00:00</EndDateLocal>
                    <ConfirmationNumber>F1672664579</ConfirmationNumber>
                    <StartCityCode>SEA</StartCityCode>
                    <EndCityCode>SEA</EndCityCode>
                    <StartLocation>SEA</StartLocation>
                    <EndLocation>SEA</EndLocation>
                    <Class>E</Class>
                    <Body>C</Body>
                    <Transmission>M</Transmission>
                    <AirCondition>R</AirCondition>
                    <NumCars>1</NumCars>
                    <DiscountCode>346660</DiscountCode>
                    <DailyRate>44.0000</DailyRate>
                    <TotalRate>44.0000</TotalRate>
                    <RateType>D</RateType>
                    <Currency>USD</Currency>
                    <Charges>
                        <Fixed>
                            <Description>Dropoff Fee</Description>
                            <Currency>USD</Currency>
                            <Amount>0.0000</Amount>
                            <IsPrimary>false</IsPrimary>
                            <SemanticsCode>DROPOFFFEE</SemanticsCode>
                            <SemanticsVendorType>C</SemanticsVendorType>
                        </Fixed>
                        <RateWithAllowance>
                            <Currency>USD</Currency>
                            <Amount>44.0000</Amount>
                            <StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
                            <IsPrimary>true</IsPrimary>
                            <SemanticsCode>DAYS</SemanticsCode>
                            <SemanticsVendorType>C</SemanticsVendorType>
                            <PerUnit>DAY</PerUnit>
                            <NumUnits>1.0000</NumUnits>
                            <AllowanceNumUnits>250.0000</AllowanceNumUnits>
                            <AllowanceAmount>0.2400</AllowanceAmount>
                            <AllowanceIsUnlimited>false</AllowanceIsUnlimited>
                        </RateWithAllowance>
                    </Charges>
                </Car>
            </Segments>
            <Passengers>
                <Passenger>
                    <NameFirst>Chris</NameFirst>
                    <NameLast>Miller</NameLast>
                </Passenger>
            </Passengers>
            <RecordLocator>C123456789</RecordLocator>
            <BookingSource>TravelBookings.com</BookingSource>
            <DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
            <ItinSourceName>ConcurConnectAPI</ItinSourceName>
            <PassengerCount>1</PassengerCount>
        </Booking>
        <Booking>
            <Segments>
                <Hotel>
                    <Vendor>CQ</Vendor>
                    <Status>GK</Status>
                    <StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
                    <EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
                    <ConfirmationNumber>3364214265</ConfirmationNumber>
                    <RateCode>LV4</RateCode>
                    <Name>CONCUR HOTEL</Name>
                    <HotelPropertyId>CONQ</HotelPropertyId>
                    <CheckinTime>03:00 PM</CheckinTime>
                    <CheckoutTime>12:00 PM</CheckoutTime>
                    <NumPersons>1</NumPersons>
                    <NumRooms>1</NumRooms>
                    <CancellationPolicy>Cxl 1 day prior to Arrival</CancellationPolicy>
                    <DailyRate>240.3500</DailyRate>
                    <Currency>USD</Currency>
                    <RoomDescription>1 KING BED ACCESSIBLE ROOM - K1RRC</RoomDescription>
                    <Charges>
                        <Rate>
                            <Currency>USD</Currency>
                            <Amount>240.3500</Amount>
                            <StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
                            <IsPrimary>false</IsPrimary>
                            <SemanticsCode>ROOMRATE</SemanticsCode>
                            <SemanticsVendorType>H</SemanticsVendorType>
                            <PerUnit>DAY</PerUnit>
                            <NumUnits>3.0000</NumUnits>
                        </Rate>
                    </Charges>
                </Hotel>
            </Segments>
            <Passengers>
                <Passenger>
                    <NameFirst>Chris</NameFirst>
                    <NameLast>Miller</NameLast>
                </Passenger>
            </Passengers>
            <RecordLocator>0987654321</RecordLocator>
            <BookingSource>TravelBookings.com</BookingSource>
            <DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
            <OriginalItinLocator>33491211</OriginalItinLocator>
            <ItinSourceName>ConcurConnectAPI</ItinSourceName>
            <PassengerCount>1</PassengerCount>
        </Booking>
    </Bookings>
</Itinerary>

Post Itinerary Details Response

HTTP Responses Supported Content Types
HTTP Status Codes application/xml

Content Body

When the trip is created successfully, the request will return the full posted trip details with the following additional elements inside the Itinerary parent element:

Element Description
id The URI containing the trip ID.
ItinLocator The Itinerary Locator value (trip ID without the URL). The ItinLocator value is used when updating an existing trip.
DateModifiedUtc The UTC formatted date that this booking was last modified.
BookedVia The GDS the itinerary was booked in.
DateBookedLocal The date, in the traveler's local time, that the booking was made.

Agency Proposal

The response will include the CustomAttributes element and its child elements if the request was an Agency Proposal.

XML Example of Successful Response

<Itinerary xmlns="http://www.concursolutions.com/api/travel/trip/2010/06">
    <id>https://www.concursolutions.com/api/travel/trip/v1.1/CNQR1234567890</id>
    <ItinLocator>CNQR1234567890</ItinLocator>
    <ClientLocator>KK-CNQ-1M1P6-5HJ</ClientLocator>
    <ItinSourceName>ConcurTravel</ItinSourceName>
    <TripName>Trip from Dallas to Seattle</TripName>
    <Comments />
    <StartDateLocal>2013-12-21T07:25:00</StartDateLocal>
    <EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
    <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
    <BookedVia>EveryGDS</BookedVia>
    <BookedByFirstName>Chris</BookedByFirstName>
    <BookedByLastName>Miller</BookedByLastName>
    <DateBookedLocal>2012-07-24T19:15:52</DateBookedLocal>
    <Bookings>
        <Booking>
            <Segments>
                <Car>
                    <Vendor>CQ</Vendor>
                    <Status>HK</Status>
                    <StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
                    <EndDateLocal>2013-12-24T12:00:00</EndDateLocal>
                    <ConfirmationNumber>F1672664579</ConfirmationNumber>
                    <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
                    <StartCityCode>SEA</StartCityCode>
                    <EndCityCode>SEA</EndCityCode>
                    <StartLocation>SEA</StartLocation>
                    <EndLocation>SEA</EndLocation>
                    <Class>E</Class>
                    <Body>C</Body>
                    <Transmission>M</Transmission>
                    <AirCondition>R</AirCondition>
                    <NumCars>1</NumCars>
                    <DiscountCode>346660</DiscountCode>
                    <DailyRate>44.0000</DailyRate>
                    <TotalRate>44.0000</TotalRate>
                    <RateType>D</RateType>
                    <Currency>USD</Currency>
                    <Charges>
                        <Fixed>
                            <Description>Dropoff Fee</Description>
                            <Currency>USD</Currency>
                            <Amount>0.0000</Amount>
                            <IsPrimary>false</IsPrimary>
                            <SemanticsCode>DROPOFFFEE</SemanticsCode>
                            <SemanticsVendorType>C</SemanticsVendorType>
                        </Fixed>
                        <RateWithAllowance>
                            <Currency>USD</Currency>
                            <Amount>44.0000</Amount>
                            <StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
                            <IsPrimary>true</IsPrimary>
                            <SemanticsCode>DAYS</SemanticsCode>
                            <SemanticsVendorType>C</SemanticsVendorType>
                            <PerUnit>DAY</PerUnit>
                            <NumUnits>1.0000</NumUnits>
                            <AllowanceNumUnits>250.0000</AllowanceNumUnits>
                            <AllowanceAmount>0.2400</AllowanceAmount>
                            <AllowanceIsUnlimited>false</AllowanceIsUnlimited>
                        </RateWithAllowance>
                    </Charges>
                </Car>
            </Segments>
            <Passengers>
                <Passenger>
                    <NameFirst>Chris</NameFirst>
                    <NameLast>Miller</NameLast>
                </Passenger>
            </Passengers>
            <RecordLocator>C123456789</RecordLocator>
            <BookingSource>ConcurCars</BookingSource>
            <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
            <DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
            <ItinSourceName>TravelSupplier</ItinSourceName>
            <PassengerCount>1</PassengerCount>
        </Booking>
        <Booking>
            <Segments>
                <Hotel>
                    <Vendor>CQ</Vendor>
                    <Status>GK</Status>
                    <StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
                    <EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
                    <ConfirmationNumber>3364214265</ConfirmationNumber>
                    <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
                    <RateCode>LV4</RateCode>
                    <Name>CONCUR HOTEL</Name>
                    <HotelPropertyId>CONQ</HotelPropertyId>
                    <CheckinTime>00:00</CheckinTime>
                    <CheckoutTime>00:00</CheckoutTime>
                    <NumPersons>1</NumPersons>
                    <NumRooms>1</NumRooms>
                    <CancellationPolicy>Cxl 1 day prior to Arrival</CancellationPolicy>
                    <DailyRate>240.3500</DailyRate>
                    <Currency>USD</Currency>
                    <RoomDescription>1 KING BED ACCESSIBLE ROOM - K1RRC</RoomDescription>
                    <Charges>
                        <Rate>
                            <Currency>USD</Currency>
                            <Amount>240.3500</Amount>
                            <StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
                            <IsPrimary>false</IsPrimary>
                            <SemanticsCode>ROOMRATE</SemanticsCode>
                            <SemanticsVendorType>H</SemanticsVendorType>
                            <PerUnit>DAY</PerUnit>
                            <NumUnits>3.0000</NumUnits>
                        </Rate>
                    </Charges>
                </Hotel>
            </Segments>
            <Passengers>
                <Passenger>
                    <NameFirst>Chris</NameFirst>
                    <NameLast>Miller</NameLast>
                </Passenger>
            </Passengers>
            <RecordLocator>0987654321</RecordLocator>
            <BookingSource>ConcurHotel</BookingSource>
            <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
            <DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
            <OriginalItinLocator>33491211</OriginalItinLocator>
            <ItinSourceName>ConcurTravel</ItinSourceName>
            <PassengerCount>1</PassengerCount>
        </Booking>
    </Bookings>
</Itinerary>

XML Example of Successful Response for Agency Proposal

<Itinerary xmlns="http://www.concursolutions.com/api/travel/trip/2010/06">
    <id>https://www.concursolutions.com/api/travel/trip/v1.1/CNQR1234567890</id>
    <ItinLocator>CNQR1234567890</ItinLocator>
    <ClientLocator>KK-CNQ-1M1P6-5HJ</ClientLocator>
    <ItinSourceName>ConcurTravel</ItinSourceName>
    <TripName>Trip from Dallas to Seattle</TripName>
    <Comments />
    <StartDateLocal>2013-12-21T07:25:00</StartDateLocal>
    <EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
    <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
    <BookedVia>EveryGDS</BookedVia>
    <BookedByFirstName>Chris</BookedByFirstName>
    <BookedByLastName>Miller</BookedByLastName>
    <DateBookedLocal>2012-07-24T19:15:52</DateBookedLocal>
    <Bookings>
        <Booking>
            <Segments>
                <Car>
                    <Vendor>CQ</Vendor>
                    <Status>HK</Status>
                    <StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
                    <EndDateLocal>2013-12-24T12:00:00</EndDateLocal>
                    <ConfirmationNumber>F1672664579</ConfirmationNumber>
                    <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
                    <StartCityCode>SEA</StartCityCode>
                    <EndCityCode>SEA</EndCityCode>
                    <StartLocation>SEA</StartLocation>
                    <EndLocation>SEA</EndLocation>
                    <Class>E</Class>
                    <Body>C</Body>
                    <Transmission>M</Transmission>
                    <AirCondition>R</AirCondition>
                    <NumCars>1</NumCars>
                    <DiscountCode>346660</DiscountCode>
                    <DailyRate>44.0000</DailyRate>
                    <TotalRate>44.0000</TotalRate>
                    <RateType>D</RateType>
                    <Currency>USD</Currency>
                    <Charges>
                        <Fixed>
                            <Description>Dropoff Fee</Description>
                            <Currency>USD</Currency>
                            <Amount>0.0000</Amount>
                            <IsPrimary>false</IsPrimary>
                            <SemanticsCode>DROPOFFFEE</SemanticsCode>
                            <SemanticsVendorType>C</SemanticsVendorType>
                        </Fixed>
                        <RateWithAllowance>
                            <Currency>USD</Currency>
                            <Amount>44.0000</Amount>
                            <StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
                            <IsPrimary>true</IsPrimary>
                            <SemanticsCode>DAYS</SemanticsCode>
                            <SemanticsVendorType>C</SemanticsVendorType>
                            <PerUnit>DAY</PerUnit>
                            <NumUnits>1.0000</NumUnits>
                            <AllowanceNumUnits>250.0000</AllowanceNumUnits>
                            <AllowanceAmount>0.2400</AllowanceAmount>
                            <AllowanceIsUnlimited>false</AllowanceIsUnlimited>
                        </RateWithAllowance>
                    </Charges>
                </Car>
            </Segments>
            <Passengers>
                <Passenger>
                    <NameFirst>Chris</NameFirst>
                    <NameLast>Miller</NameLast>
                </Passenger>
            </Passengers>
            <RecordLocator>C123456789</RecordLocator>
            <BookingSource>ConcurCars</BookingSource>
            <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
            <DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
            <ItinSourceName>TravelSupplier</ItinSourceName>
            <PassengerCount>1</PassengerCount>
        </Booking>
        <Booking>
            <Segments>
                <Hotel>
                    <Vendor>CQ</Vendor>
                    <Status>GK</Status>
                    <StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
                    <EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
                    <ConfirmationNumber>3364214265</ConfirmationNumber>
                    <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
                    <RateCode>LV4</RateCode>
                    <Name>CONCUR HOTEL</Name>
                    <HotelPropertyId>CONQ</HotelPropertyId>
                    <CheckinTime>00:00</CheckinTime>
                    <CheckoutTime>00:00</CheckoutTime>
                    <NumPersons>1</NumPersons>
                    <NumRooms>1</NumRooms>
                    <CancellationPolicy>Cxl 1 day prior to Arrival</CancellationPolicy>
                    <DailyRate>240.3500</DailyRate>
                    <Currency>USD</Currency>
                    <RoomDescription>1 KING BED ACCESSIBLE ROOM - K1RRC</RoomDescription>
                    <Charges>
                        <Rate>
                            <Currency>USD</Currency>
                            <Amount>240.3500</Amount>
                            <StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
                            <IsPrimary>false</IsPrimary>
                            <SemanticsCode>ROOMRATE</SemanticsCode>
                            <SemanticsVendorType>H</SemanticsVendorType>
                            <PerUnit>DAY</PerUnit>
                            <NumUnits>3.0000</NumUnits>
                        </Rate>
                    </Charges>
                </Hotel>
            </Segments>
            <Passengers>
                <Passenger>
                    <NameFirst>Chris</NameFirst>
                    <NameLast>Miller</NameLast>
                </Passenger>
            </Passengers>
            <RecordLocator>0987654321</RecordLocator>
            <BookingSource>ConcurHotel</BookingSource>
            <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
            <DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
            <OriginalItinLocator>33491211</OriginalItinLocator>
            <ItinSourceName>ConcurTravel</ItinSourceName>
            <PassengerCount>1</PassengerCount>
        </Booking>
    </Bookings>
    <CustomAttributes>
        <CustomAttribute>
            <ExternalId />
            <DataType>Numeric</DataType>
            <Name>ProposalBatchSize</Name>
            <DisplayTitle />
            <Data>3</Data>
            <DisplayOnItinerary>true</DisplayOnItinerary>
        </CustomAttribute>
        <CustomAttribute>
            <ExternalId />
            <DataType>Numeric</DataType>
            <Name>ProposalSequenceIndex</Name>
            <DisplayTitle />
            <Data>1</Data>
            <DisplayOnItinerary>true</DisplayOnItinerary>
        </CustomAttribute>
    </CustomAttributes>
</Itinerary>

Post Itinerary Cancellation Request

Description Supported Content Types
Cancels all segments in the supplied trip.
This endpoint can be used to cancel trips for a user that is not the OAuth consumer. This is most often done when a travel supplier or Travel Management Company needs to cancel a trip on behalf of a user. The supplier or TMC must be registered with SAP Concur and have an SAP Concur account with one of the following user roles: Web Services Administrator for Professional, or Can Administer for Standard.
application/xml

Query Parameters - Required

Example:
https://www.concursolutions.com/api/travel/trip/v1.1/cancel?tripId={_tripId_}

Query Parameters - Optional

Example:
https://www.concursolutions.com/api/travel/trip/v1.1/cancel?tripId={_tripId_}&userid_type=login_id&userid_value={_loginID_}

Request Headers - Required Request Headers - Optional
Authorization header with OAuth token for a valid SAP Concur user. The OAuth consumer must have one of the following user roles in SAP Concur: Company Administrator or Web Services Administrator for Professional, or Can Administer for Standard. None

XML Example Request

POST /api/travel/trip/v1.1/cancel?tripId=CNQR1234567890 HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
...

POST Itinerary Cancellation

HTTP Responses Supported Content Types
HTTP Status Codes application/xml

Content Body

The request will return the full trip details for the cancelled trip. The trip will contain no segments, as those are all cancelled. The response includes the following additional elements inside the Itinerary parent element:

Element Description
id The URI containing the trip ID.
ItinLocator The Itinerary Locator value (trip ID without the URL).
ClientLocator The identifier for the client.
DateModifiedUtc The UTC formatted date that this booking was last modified.
BookedVia The GDS the itinerary was booked in.
DateBookedLocal The date, in the traveler's local time, that the booking was made.

XML Example of Successful Response

<Itinerary xmlns="http://www.concursolutions.com/api/travel/trip/2010/06">
    <id>https://www.concursolutions.com/api/travel/trip/v1.1/CNQR1234567890</id>
    <ItinLocator>CNQR1234567890</ItinLocator>
    <ClientLocator>KK-CNQ-1M1P6-5HJ</ClientLocator>
    <ItinSourceName>ConcurTravel</ItinSourceName>
    <TripName>Trip from Dallas to Seattle</TripName>
    <Comments />
    <StartDateLocal>2013-12-21T07:25:00</StartDateLocal>
    <EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
    <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
    <BookedVia>EveryGDS</BookedVia>
    <BookedByFirstName>Chris</BookedByFirstName>
    <BookedByLastName>Miller</BookedByLastName>
    <DateBookedLocal>2012-07-24T19:15:52</DateBookedLocal>
    <Bookings>
        <Booking>
            <Segments/>
            <Passengers>
                <Passenger>
                    <NameFirst>Chris</NameFirst>
                    <NameLast>Miller</NameLast>
                </Passenger>
            </Passengers>
            <RecordLocator>C123456789</RecordLocator>
            <BookingSource>ConcurCars</BookingSource>
            <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
            <DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
            <ItinSourceName>TravelSupplier</ItinSourceName>
            <PassengerCount>1</PassengerCount>
        </Booking>
        <Booking>
            <Segments/>
            <Passengers>
                <Passenger>
                    <NameFirst>Chris</NameFirst>
                    <NameLast>Miller</NameLast>
                </Passenger>
            </Passengers>
            <RecordLocator>0987654321</RecordLocator>
            <BookingSource>ConcurHotel</BookingSource>
            <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
            <DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
            <OriginalItinLocator>33491211</OriginalItinLocator>
            <ItinSourceName>ConcurTravel</ItinSourceName>
            <PassengerCount>1</PassengerCount>
        </Booking>
    </Bookings>
</Itinerary>

POST Booking Details

Creates a new booking or updates an existing booking. A new booking will be assigned to the specified trip, or if no trip is specified, the first itinerary that spans the booking dates. If no trip is specified and no itinerary exists that spans the booking dates, a new itinerary will be created.

This endpoint can be used to create/update bookings for a user that is not the OAuth consumer. This is most often done when a travel supplier or Travel Management Company needs to create/update a booking on behalf of a user. The supplier or TMC must be registered with SAP Concur, and must have an account that has one of the following user roles: Web Services Administrator for Professional, or Can Administer for Standard.

POST /api/travel/booking/v1.0?tripId=12345678 HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}

Request Parameters

Query Parameters - Optional

Examples:

https://www.concursolutions.com/api/travel/booking/v1.1?tripId={tripId}

https://www.concursolutions.com/api/travel/booking/v1.1?userid_type=login_id&userid_value={loginID}

Request Body Root Elements

The request contains a Booking parent element with the following child elements:

Required Element Description
BookingSource The supplier's name.
ItinSourceName The itinerary source. Format: TravelSupplier
RecordLocator Record locator for this booking. This is often six alphanumeric characters but can have other formats depending on the booking source
Optional Element Description
DateBookedLocal The date the booking was created, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss
FormOfPaymentName The name of the form of payment for the booking.
FormOfPaymentType The type of the form of payment.
TicketMailingAddress The mailing address for the booked ticket, if available.
TicketPickupLocation The pickup location for the booked ticket, if available
TicketPickupNumber The confirmation number to pick up the booked ticket, if available.
AirfareQuotes List of stored airfare quotes for this booking.
AirlineTickets List of Airline Tickets for this booking.
Charges List of Charges for this booking.
MiscChargeOrders List of Miscellaneous AirCharges for this booking.
Passengers The Passengers element contains child element for each booked passenger. The description of each child element can be seen in a subsequent table.
PassPrograms List of Pass Programs for this booking.
PhoneNumbers List of Phone numbers associated with this booking.
RailPayments List of Rail payments associated with rail segments in this booking.
Segments List of Segments in this booking. This parent element contains one or more Air, Car, Hotel, Dining, Ride, Rail, Parking, or Event parent elements for the booking.
Delivery The method this booking was delivered. 
WaitListSegments The segments that the traveler is waitlisted for this booking.
Warnings The warnings associated with the booking.
WebAddresses List of web addresses such as emails, pickup URLs, etc. associated with this booking
BookingReferrer BookingReferrer is used only in specific source tracking scenarios when there is a need to distinguish between bookings with the same BookingSources coming through different flows. Do not populate without coordinating with your technical contact. The supported values are: Concur Travel, Sign-in with SAP Concur, Supplier Mobile, Supplier Web

Passenger Child Elements

Required Element Description
NameFirst The first name of the passenger.
NameLast The last name of the passenger.
Optional Element Description
NameMiddle The middle name of the passenger.
NamePrefix The name prefix of the passenger.
NameRemark Additional details about the passenger's name.
NameSuffix The name suffix of the passenger.
NameTitle The title of the passenger.
TextName The user's full name as entered in the booking tool if different from the name in the database.
FrequentTravelerProgram Passenger's loyalty programs

Response

This function returns the full trip details.

If the end user updates an existing reservation which results in a new confirmation number, the old booking must be explicitly cancelled in addition to posting the new booking to SAP Concur. If the previous booking is not cancelled, the user will see both bookings in their SAP Concur trip list.

Examples

Example 1: XML Example Request

POST /api/travel/booking/v1.0?tripId=12345678 HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
Content-Type: application/xml
...

<Booking xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <Segments>
        <Car>
            <Vendor>AL</Vendor>
            <VendorName>Alamo</VendorName>
            <Status>HK</Status>
            <StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
            <EndDateLocal>2013-12-23T12:00:00</EndDateLocal>
            <StartDateUtc>2013-12-21T20:00:00</StartDateUtc>
            <EndDateUtc>2013-12-23T20:00:00</EndDateUtc>
            <ConfirmationNumber>F16726AIUS</ConfirmationNumber>
            <DateCreatedUtc>2012-07-22T11:55:42</DateCreatedUtc>
            <DateModifiedUtc>2012-07-22T11:55:42</DateModifiedUtc>
            <StartCityCode>SEA</StartCityCode>
            <EndCityCode>SEA</EndCityCode>
            <StartLocation>SEA</StartLocation>
            <EndLocation>SEA</EndLocation>
            <Class>E</Class>
            <Body>C</Body>
            <Transmission>A</Transmission>
            <AirCondition>R</AirCondition>
            <NumPersons>1</NumPersons>
            <NumCars>1</NumCars>
            <DiscountCode>4321</DiscountCode>
            <DailyRate>35.0000</DailyRate>
            <TotalRate>105.0000</TotalRate>
            <RateType>D</RateType>
            <Currency>USD</Currency>
        </Car>
    </Segments>
    <RecordLocator>PANAMA50</RecordLocator>
    <BookingSource>Alamo</BookingSource>
    <DateCreatedUtc>2012-07-22T11:55:42</DateCreatedUtc>
    <DateModifiedUtc>2012-07-22T11:55:42</DateModifiedUtc>
    <DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
    <ItinSourceName>TravelSupplier</ItinSourceName>
    <Passengers>
        <Passenger>
            <PassengerKey>0</PassengerKey>
            <NameFirst>Chris</NameFirst>
            <NameLast>Miller</NameLast>
        </Passenger>
    </Passengers>
</Booking>

Example 2: XML Example of Successful Response

<Itinerary xmlns="https://www.concursolutions.com/api/travel/trip/2010/06">
    <id>https://www.concursolutions.com/api/travel/trip/v1.1/CNQR1234567890</id>
    <ItinLocator>CNQR1234567890</ItinLocator>
    <ClientLocator>KK-CNQ-1M1P6-5HJ</ClientLocator>
    <ItinSourceName>TravelSupplier</ItinSourceName>
    <TripName>Trip to Seattle</TripName>
    <Comments />
    <StartDateLocal>2013-12-21T07:25:00</StartDateLocal>
    <EndDateLocal>2013-12-23T23:59:00</EndDateLocal>
    <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
    <BookedVia>EveryGDS</BookedVia>
    <BookedByFirstName>Chris</BookedByFirstName>
    <BookedByLastName>Miller</BookedByLastName>
    <DateBookedLocal>2012-07-24T19:15:52</DateBookedLocal>
    <Booking>
        <Segments>
            <Car>
                <Vendor>AL</Vendor>
                <VendorName>Alamo</VendorName>
                <Status>HK</Status>
                <StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
                <EndDateLocal>2013-12-23T12:00:00</EndDateLocal>
                <StartDateUtc>2013-12-21T20:00:00</StartDateUtc>
                <EndDateUtc>2013-12-23T20:00:00</EndDateUtc>
                <ConfirmationNumber>F16726AIUS</ConfirmationNumber>
                <DateCreatedUtc>2012-07-22T11:55:42</DateCreatedUtc>
                <DateModifiedUtc>2012-07-22T11:55:42</DateModifiedUtc>
                <StartCityCode>SEA</StartCityCode>
                <EndCityCode>SEA</EndCityCode>
                <StartLocation>SEA</StartLocation>
                <EndLocation>SEA</EndLocation>
                <Class>E</Class>
                <Body>C</Body>
                <Transmission>A</Transmission>
                <AirCondition>R</AirCondition>
                <NumPersons>1</NumPersons>
                <NumCars>1</NumCars>
                <DiscountCode>4321</DiscountCode>
                <DailyRate>35.0000</DailyRate>
                <TotalRate>105.0000</TotalRate>
                <RateType>D</RateType>
                <Currency>USD</Currency>
            </Car>
        </Segments>
        <RecordLocator>PANAMA50</RecordLocator>
        <BookingSource>Alamo</BookingSource>
        <DateCreatedUtc>2012-07-22T11:55:42</DateCreatedUtc>
        <DateModifiedUtc>2012-07-22T11:55:42</DateModifiedUtc>
        <DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
        <ItinSourceName>TravelSupplier</ItinSourceName>
        <Passengers>
            <Passenger>
                <PassengerKey>0</PassengerKey>
                <NameFirst>Chris</NameFirst>
                <NameLast>Miller</NameLast>
            </Passenger>
        </Passengers>
    </Booking>
</Itinerary>

POST Booking Cancellation

Cancels an existing booking. By default, the OAuth consumer should be the owner of the booking. This endpoint can also be used to cancel bookings that the OAuth consumer does not own. This is most often done when a Travel Management Company needs to cancel bookings on behalf of a user. The TMC must be registered with SAP Concur and have an SAP Concur account that has one of the following user roles: Web Services Administrator for Professional, or Can Administer for Standard.

NOTE:
Booking records can only be updated by the booking source that created them. SAP Concur verifies the source information before processing the request.

POST /api/travel/booking/v1.1/cancel?bookingSource={FastTravel}&confirmationNumber={098765431} HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}

Request Parameters

Query Parameters - Required

The cancel keyword and the unique identifier for the supplier, configured by SAP Concur during the application review. The bookingSource must match the Supplier Name associated with the booking.

The confirmation number for the booking to cancel.

Example: https://www.concursolutions.com/api/travel/booking/v1.1/cancel?bookingSource={Supplier}&confirmationNumber={confnum}

Query Parameters - Optional

The SAP Concur login ID of the user who owns the booking. Only provided when the booking owner is not the OAuth consumer. Can only be used when the OAuth consumer has the required user role.

Example: https://www.concursolutions.com/api/travel/booking/v1.1/cancel?bookingSource={Supplier}&confirmationNumber={confnum}&userid_type=login_id&userid_value={loginID}

Content Type

application/xml

Authorization Header

The authorization header must have an OAuth token for a valid SAP Concur user. The OAuth consumer must be registered as a Supplier or TMC with SAP Concur, and must have one of the following user roles in SAP Concur: Company Administrator or Web Services Administrator for Professional, or Can Administer for Standard.

Response

This function returns the full booking details. If the booking is not found, the function returns a HTTP 404 error and the following element:

Status: This element contains the value: NotFound.

Examples

Examples 1: XML Example Request

POST /api/travel/booking/v1.1/cancel?bookingSource={FastTravel}&confirmationNumber={098765431} HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}

Examples 2: XML Example of Successful Response

<Car>
    <Vendor>ZE</Vendor>
    <Status>HK</Status>
    <StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
    <EndDateLocal>2013-12-24T12:00:00</EndDateLocal>
    <TimeZoneId xsi:nil="true"/>
    <StartDateUtc>2013-12-21T20:00:00</StartDateUtc>
    <EndDateUtc>2013-12-24T20:00:00</EndDateUtc>
    <ConfirmationNumber>0987654321</ConfirmationNumber>
    <CancellationNumber>1029384756</CancellationNumber>
    <DateCreatedUtc>2012-07-22T11:55:42</DateCreatedUtc>
    <DateCancelledUtc>2012-07-25T14:21:35</DateCancelledUtc>
    <DateModifiedUtc>2012-07-22T11:55:42</DateModifiedUtc>
    <UpgradedDateTime xsi:nil="true"/>
    <IsUpgradeAllowed xsi:nil="true"/>
    <FrequentTravelerId/>
    <StartCityCode>SEA</StartCityCode>
    <EndCityCode>SEA</EndCityCode>
    <StartLocation>SEA</StartLocation>
    <EndLocation>SEA</EndLocation>
    <Class>E</Class>
    <Body>C</Body>
    <Transmission>M</Transmission>
    <AirCondition>R</AirCondition>
    <PhoneNumber/>
    <NumPersons xsi:nil="true"/>
    <NumCars>1</NumCars>
    <DiscountCode>346660</DiscountCode>
    <Charges>
        <Fixed>
            <Description>Dropoff Fee</Description>
            <Currency>USD</Currency>
            <Amount>0.0000</Amount>
            <StartDateLocal xsi:nil="true"/>
            <IsPaid xsi:nil="true"/>
            <SemanticsCode>DROPOFFFEE</SemanticsCode>
            <SemanticsVendorType>C</SemanticsVendorType>
        </Fixed>
        <RateWithAllowance>
            <Currency>USD</Currency>
            <Amount>44.0000</Amount>
            <StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
            <IsPaid xsi:nil="true"/>
            <SemanticsCode>DAYS</SemanticsCode>
            <SemanticsVendorType>C</SemanticsVendorType>
            <PerUnit>DAY</PerUnit>
            <NumUnits>1.0000</NumUnits>
            <AllowanceUnit/>
            <AllowanceNumUnits>250.0000</AllowanceNumUnits>
            <AllowanceAmount>0.2400</AllowanceAmount>
            <AllowanceIsUnlimited>false</AllowanceIsUnlimited>
        </RateWithAllowance>
    </Charges>
    <Remarks/>
    <PerDiemLocation/>
</Car>

Booking Object Elements

The booking elements contain many child elements. For ease of use, these elements are divided into the Core Elements, which are the most frequently used, and Additional Elements, which are not often used but are supported by the Itinerary web service. Some elements only appear if the travel supplier created the booking. Elements are marked as required if they must be supplied for a new booking.

NOTE: TripLink - Open Booking suppliers see a targeted subset of these fields. Refer to the documentation here for the TripLink - Open Booking supplier booking object elements.

Air Booking Elements

Core Elements - Required

Element Description
ClassOfService The class of the booking.
ConfirmationNumber The record locator or confirmation number for the flight from the airline.
EndCityCode The IATA airport code for the end city of the booking.
EndDateLocal The booking ending time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss
FlightNumber The flight number for the booking.
StartCityCode The IATA airport code for the starting address for the booking.
StartDateLocal The booking starting time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss
Vendor The two letter GDS vendor code. Use $$ when not available.

Core Elements - Optional

Element Description
CancellationNumber The cancellation number from the vendor. This field should be set when you cancel a segment.
CancellationPolicy The cancellation policy from the vendor.
Charges The charges for this booking. Refer to the Charges Child Elements table.
DateCancelledUtc The date the booking was cancelled, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateCreatedUtc The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateModifiedUtc The date the booking was modified, in UTC. Format: YYYY-MM-DDThh:mm:ss
EndDateUtc The booking ending time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss
EndGate The arrival gate for the booking.
EndTerminal The arrival terminal for the booking.
LegId The leg ID of the booking. Leg IDs do not change on a connection. For each unique leg ID in the trip, all flights subsequent to the first segment with the same leg ID are connections.
Seats The seats for the booking. This parent element contains an AirSeat element for each included seat. The AirSeat element contains the following child elements: PassengerRph - The passenger assigned to the seat. SeatNumber - The number of the seat.
StartDateUtc The booking starting time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss
StartGate The departure gate for the booking.
StartTerminal The departure terminal for the booking.
Status The GDS based booking status for the segment such as HK, HL, BK, etc.
TimeZone The time zone of the booking. Format: One of the supported Olson or Windows Time Zones.

Additional Elements - Optional

Element Description
AircraftCode The code for the aircraft type.
Bags The number of bags included in the booking.
Cabin The section of the airplane for the booking.
CarbonEmissionLbs The pounds of carbon emission for this booking.
CarbonModel The model used to calculate the carbon emissions.
CheckedBaggage Whether the booking includes checked baggage.
Duration The duration of the booked flight.
ETicket Whether the booking has an e-ticket. Format: Y/N
IsOpenSegment Whether the segment is open. Format: True/False
IsPreferredVendor If the airline is marked as a preferred property by the company. Format: True/False
IsUpgradeAllowed Whether the booking can be upgraded. Format: True/False
Meals The meals included in the booking.
Miles The number of miles included in the booking.
Notes Additional details about the booking.
OpenSegment Additional information about the open segment.
OperatedByFlightNumber Flight Number provided by the airline operating the flight on behalf of the booked airline.
OperatedByVendor The airline operating the flight on behalf of the booked airline.
OperatedByVendorName The name of the airline operating the flight on behalf of the booked airline.
Services The services included in the booking.
SpecialInstructions Additional instructions regarding the booking. Max Length: 256
UpgradedDateTime The date and time the booking was upgraded. Format: YYYY-MM-DDThh:mm:ss

Car Booking Elements

Core Elements - Required

Element Description
ConfirmationNumber The confirmation number from the vendor.
EndDateLocal The booking ending time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss
StartDateLocal The booking starting time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss
Vendor The two letter GDS vendor code.

Core Elements - Optional

Element Description
CancellationNumber The cancellation number from the vendor. This field should be set when you cancel a segment.
CancellationPolicy The cancellation policy from the vendor.
Charges The charges for this booking. Refer to the Charges Child Elements table.
Currency The 3-letter ISO 4217 currency code for the booking.
DailyRate The daily rate for the booking.
DateCancelledUtc The date the booking was cancelled, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateCreatedUtc The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateModifiedUtc The date the booking was modified, in UTC. Format: YYYY-MM-DDThh:mm:ss
EndCityCode The IATA airport code for the ending address for the booking.
EndDateUtc The booking ending time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss
EndLatitude The latitude for the ending location of the booking.
EndLongitude The longitude for the ending location of the booking.
Notes Additional information about the booking.
PhoneNumber The phone number for the user.
RateCode The rate code for the booking.
StartCityCode The IATA airport code for the starting address for the booking.
StartDateUtc The booking starting time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss
StartLatitude The latitude for the starting location of the booking.
StartLongitude The longitude for the starting location of the booking.
Status The booking status.
TimeZone The time zone of the booking. Format: One of the supported Olson or Windows Time Zones.
TotalRate The total rate amount of the booking.
VendorName The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary.

Additional Elements - Optional

Element Description
AirCondition The character code that indicates if car has an air conditioner. R for AC, N for No AC
Body The character code to indicate how many passengers the car can seat.
Class Character code to indicate the class of the car e.g. if it is economy, full size, compact, etc. Varies by Vendor
DiscountCode The discount code used by the company/TMC to get a discounted rate.
DropoffCollectionAddress1 The AddressLine1 for the dropoff address when the rental service offers dropoff.
DropoffCollectionAddressType  
DropoffCollectionCategory  
DropoffCollectionCity City for the dropoff address when the rental service offers dropoff.
DropoffCollectionCityCode The IATA airport code for the dropoff address when the rental service offers dropoff.
DropoffCollectionCountry The country for the dropoff address when the rental service offers dropoff.
DropoffCollectionLatitude The latitude for the dropoff address when the rental service offers dropoff.
DropoffCollectionLongitude The longitude for the dropoff address when the rental service offers dropoff.
DropoffCollectionNumber  
DropoffCollectionPhoneNumber The phone number for the dropoff address when the rental service offers dropoff.
DropoffCollectionPostalCode The postal code for the dropoff address when the rental service offers dropoff.
DropoffCollectionState The state for the dropoff address when the rental service offers dropoff.
EndAddress The ending address for the booking.
EndAddress2 The ending address for the booking.
EndCity The ending address for the booking.
EndCloseTime The closing time for the dropoff location.
EndCountry The ending address for the booking.
EndLocation The dropoff location.
EndOpenTime The opening time of the dropoff location.
EndPhoneNumber The phone number of the dropoff location.
EndPostalCode The ending address for the booking.
EndState The ending address for the booking.
FrequentTravelerId The loyalty program ID for the user.
IsUpgradeAllowed Whether the booking can be upgraded. Format: True/False
NumCars The number of cars rented.
NumPersons The number of people including the driver that the rental is for.
PickupDeliveryAddress1 The AddressLine1 for the pickup address when the rental service offers pickup.
PickupDeliveryAddressType  
PickupDeliveryCategory  
PickupDeliveryCity The city for the pickup address when the rental service offers pickup.
PickupDeliveryCityCode The IATA airport code for the pickup address when the rental service offers pickup.
PickupDeliveryCountry The country for the pickup address when the rental service offers pickup.
PickupDeliveryLatitude The latitude for the pickup address when the rental service offers pickup.
PickupDeliveryLongitude The longitude for the pickup address when the rental service offers pickup.
PickupDeliveryNumber  
PickupDeliveryPhoneNumber The phone number for the pickup address when the rental service offers pickup.
PickupDeliveryPostalCode The postal code for the pickup address when the rental service offers pickup.
PickupDeliveryState The state for the pickup address when the rental service offers pickup.
RateType The rate type for the booking.
SpecialEquipment Any special equipment required by the renter.
SpecialInstructions Additional instructions regarding the booking. Max Length: 256
StartAddress The starting address of the booking.
StartAddress2 The starting address for the booking.
StartCity The starting address for the booking.
StartCloseTime The closing time for the pickup location.
StartCountry The starting address for the booking.
StartLocation The starting location of the booking.
StartOpenTime The opening time for the pickup location.
StartPostalCode The starting address for the booking.
StartState The starting address for the booking.
Transmission The character code that indicates if the car has auto-transmission. A for Auto, M for Manual
UpgradedDateTime The date and time the booking was upgraded. Format: YYYY-MM-DDThh:mm:ss

Hotel Booking Elements

Core Elements - Required

Element Description
ConfirmationNumber The confirmation number from the vendor.
EndDateLocal The booking ending time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss
Name The hotel name for the booking.
StartCityCode The IATA airport code for the starting address for the booking.
StartDateLocal The booking starting time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss
Status The booking status.
Vendor The two letter GDS vendor code.

Core Elements - Optional

Element Description
CancellationNumber The cancellation number from the vendor. This field should be set when you cancel a segment.
CancellationPolicy The cancellation policy from the vendor.
Charges The charges for this booking. Refer to the Charges Child Elements table.
CheckinTime The check in time for the hotel booking.
CheckoutTime The check out time for the hotel booking.
Currency The 3-letter ISO 4217 currency code for the booking.
DailyRate Average per day rate for the hotel. If the rate varies over the duration, it can be specified using the charges model.
DateCancelledUtc The date the booking was cancelled, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateCreatedUtc The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateModifiedUtc The date the booking was modified, in UTC. Format: YYYY-MM-DDThh:mm:ss
EndDateUtc The booking ending time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss
HotelPropertyId The hotel's property ID.
Notes Additional information about the booking.
NumPersons The number of people the booking is for.
NumRooms The number of rooms the booking is for.
PhoneNumber The phone number for the booking.
RateCode The rate code for the booking.
RoomDescription The room description for the booking. Max Length: 200
RoomType The room type for the booking.
SpecialInstructions Additional instructions regarding the booking. Max Length: 256
StartAddress The starting address of the booking.
StartAddress2 The starting address for the booking.
StartCity The starting address for the booking.
StartCountry The starting address for the booking.
StartLatitude The latitude for the starting location of the booking.
StartLongitude The longitude for the starting location of the booking.
StartPostalCode The starting address for the booking.
StartState The starting address for the booking.
StartDateUtc The booking starting time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss
TimeZone The time zone of the booking. Format: One of the supported Olson or Windows Time Zones.
TotalRate The total rate amount of the booking.

Additional Elements - Optional

Element Description
EndCityCode The IATA airport code for the ending address for the booking.
DiscountCode The discount code for the booking.
FrequentTravelerId The traveler’s ID for the frequent traveler reward program.
HadDeposit Whether the booking had a deposit. Format: true/false
IsUpgradeAllowed Whether the booking can be upgraded. Format: true/false
ModificationCode The code for the modification to the booking.
PartnerMembershipId The membership ID of the partner associated with the booking.
PassiveType The type of the booking.
RateAccess The rate access for the booking.
RateType The rate type for the booking.
UpgradedDateTime The date and time the booking was upgraded. Format: YYYY-MM-DDThh:mm:ss
VendorFlags Semi-colon-delimited list of flags for free hotel service flags. E.g. free breakfast (FB), internet (FI), Parking (FP), etc. If they were all present they can be concatenated as - FB;FI;FP;
VendorName The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary.

Dining Booking Elements

Core Elements - Required

Element Description
ConfirmationNumber The confirmation number from the vendor.

Core Elements - Optional

Element Description
CancellationNumber The cancellation number from the vendor. This field should be set when you cancel a segment.
Charges The charges for this booking. Refer to the Charges Child Elements table.
DateCancelledUtc The date the booking was cancelled, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateCreatedUtc The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateModifiedUtc The date the booking was modified, in UTC. Format: YYYY-MM-DDThh:mm:ss
EndDateLocal The booking ending time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss
EndDateUtc The booking ending time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss
FrequentTravelerId The loyalty program ID for the user.
IsUpgradeAllowed Whether the booking can be upgraded. Format: true/false
Name The name of the restaurant. Maximum length: 80
Notes Additional information about the booking.
NumPersons The number of persons for the booking.
PhoneNumber The restaurant phone number.
RestaurantId The booking vendor’s restaurant ID. Maximum length: 50
StartAddress The restaurant address. Maximum length: 80
StartAddress2 The restaurant address. Maximum length: 80
StartCity The restaurant address. Maximum length: 50
StartCountry The restaurant address.
StartDateLocal The booking starting time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss
StartDateUtc The booking starting time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss
StartLatitude The latitude of the restaurant.
StartLongitude The longitude of the restaurant.
StartPostalCode The restaurant address. Maximum length: 24
StartState The restaurant address. Maximum length: 50
Status The status of the segment.
TimeZone The time zone of the booking. Format: One of the supported Olson or Windows Time Zones.
UpgradedDateTime The date and time the booking was upgraded. Format: YYYY-MM-DDThh:mm:ss
Vendor The two letter GDS vendor code.
VendorName The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary.

Ride Booking Elements

Core Elements - Required

Element Description
ConfirmationNumber The confirmation number from the vendor.
EndCityCode The ending IATA airport code of the booking.
StartCityCode The starting IATA airport code of the booking.
Vendor The two letter GDS vendor code. One of the following vendor codes:
Vendor Codes
Code Description
$R RideCharge
AL AddisonLee
DG DeemGroundLimo
GC GroundScope
GS GroundSpan
LC Limoscom
SQ SummitQwest
SW SummitQwest
TD Tandem
TV Transvip
$$ unknown

Core Elements - Optional

Element Description
CancellationNumber The cancellation number from the vendor. This field should be set when you cancel a segment.
CancellationPolicy The cancellation policy from the vendor.
Currency The 3-letter ISO 4217 currency code for the booking.
DateCancelledUtc The date the booking was cancelled, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateCreatedUtc The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateModifiedUtc The date the booking was modified, in UTC. Format: YYYY-MM-DDThh:mm:ss
DropoffInstructions Instructions regarding the booking.
Duration The duration of the booking.
EndAddress The ending address of the booking.
EndAddress2 The ending address of the booking.
EndCity The ending address of the booking.
EndCountry The ending address of the booking.
EndDateLocal The booking ending time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss
EndDateUtc The booking ending time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss
EndLatitude The latitude for the ending location of the booking.
EndLocation The ending location of the booking.
EndLocationCode The ending location code of the booking.
EndLocationName The ending location name of the booking.
EndLongitude The longitude of the ending point of the booking.
EndPostalCode The ending address of the booking.
EndState The ending address of the booking.
IsPersonal Whether the segment is for personal travel. Format: true/false.
IsUpgradeAllowed Whether the booking can be upgraded. Format: true/false
MeetingInstructions The instructions for the meeting location of the booking.
Miles The number of miles for the booking.
Name The name on the booking.
Notes Additional information about the booking.
NumberOfHours The number of hours of the booking.
NumPersons The number of people included in the booking.
OperatedByVendor The operated by vendor for the booking.
PassiveCityCode The passive city code of the booking.
PhoneNumber The ride vendor phone number.
PickupInstructions Instructions regarding the booking.
Rate The rate for the booking.
RateDescription The rate description for the booking.
RateNotes The rate notes for the booking.
RateType The rate type for the booking.
ReservationId The booking vendor’s reservation ID.
SpecialInstructions The special instructions for the ride. Max Length: 256
StartAddress The starting address of the booking.
StartAddress2 The starting address of the booking.
StartCity The starting address of the booking.
StartCountry The starting address of the booking.
StartDateLocal The booking starting time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss
StartDateUtc The booking starting time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss
StartLatitude The latitude of the booking start location.
StartLocation The starting location of the booking.
StartLocationCode The code of the starting location of the booking.
StartLocationName The name of the starting location of the booking.
StartLongitude The longitude of the booking start location.
StartPostalCode The starting address of the booking.
StartState The starting address of the booking.
Status The status of the segment.
TimeZone The time zone of the booking. Format: One of the supported Olson or Windows Time Zones.
UpgradedDateTime The date and time the booking was upgraded. Format: YYYY-MM-DDThh:mm:ss
VendorName The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary.
Charges The charges for this booking. Refer to the Charges Child Elements table.

Rail Booking Elements

Core Elements - Required

Element Description
ConfirmationNumber The confirmation number from the vendor.
StartDateLocal The starting date of travel for this segment, in the local time of to the starting point. Format: YYYY-MM-DDThh:mm:ss

Core Elements - Optional

Element Description
Amenities The booked amenities.
Cabin The cabin identifier.
CancellationNumber The cancellation number from the vendor. This field should be set when you cancel a segment.
CarbonEmissionLbs The pounds of carbon emission for this booking.
CarbonModel The model used to calculate the carbon emissions.
ClassOfService The class of the booking.
Currency The 3-letter ISO 4217 currency code for the booking.
DateCancelledUtc The date the booking was cancelled, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateCreatedUtc The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateModifiedUtc The date the booking was modified, in UTC. Format: YYYY-MM-DDThh:mm:ss
DiscountCode The discount code for the booking.
Duration The duration of the trip booked.
EndCity The end city for the rail trip.
EndCityCode The IATA airport code for the end city of the trip.
EndCountry The country code for the booking.
EndDateLocal The booking ending time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss
EndDateUtc The booking ending time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss
EndLatitude The latitude of the ending point of the booking.
EndLongitude The longitude of the ending point of the booking.
EndPlatform The ending platform location of the booking.
EndRailStation The code for the ending station of the booking.
EndRailStationName The name of the ending station of the booking.
ETicket The e-ticket number.
FareType The type of fare on the rail booking.
FrequentTravelerId The traveler’s ID for the frequent traveler reward program.
IsUpgradeAllowed Whether the booking can be upgraded. Format: true/false
LegId The trip leg ID.
Meals The booked meals.
Miles The number of miles booked.
Notes Additional information about the booking.
NumPersons The number of persons booked for the trip.
NumStops The number of stops in the booking.
OperatedByTrainNumber The train identifier of the operating vendor of the booked trip.
OperatedByVendor The operating vendor of the booked trip.
RateCode The vendor's code for the rate of the booking.
RouteRestrictCode The code to restrict the route of the booking.
SpecialInstructions The instructions for the booking. Max Length: 256
StartCity The starting city of the booking.
StartCityCode The IATA airport code for the starting city of the booking.
StartCountry The starting country of the booking.
StartDateUtc The starting date of travel for this segment, in UTC. Format: YYYY-MM-DDThh:mm:ss
StartLatitude The latitude of the starting location of the booking.
StartLongitude The longitude of the starting location of the booking.
StartPlatform The starting platform location of the booking.
StartRailStation The code of the starting station of the booking.
StartRailStationName The name of the starting station of the booking.
Status The booking status.
TimeZone The time zone of the booking. Format: One of the supported Olson or Windows Time Zones.
TotalRate The total rate amount of the booking.
TrainNumber The number for the booked train.
TrainTypeCode The code for the type of train used in the booking.
TrainTypeName The name of the type of train used in the booking.
TransportMode The transport mode of the booking.
UpgradedDateTime The date and time the booking was upgraded. Format: YYYY-MM-DDThh:mm:ss
Vendor The two letter GDS vendor code.
VendorName The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary.
WagonNumber The wagon number of the train car.
Charges The charges for this booking. Refer to the Charges Child Elements table.
Seats The booked seats. This parent element contains a RailSeat element for each included seat. The RailSeat element has the following child elements:
RailSeat Child Elements
Element Description
Amenities The amenities for the seat.
BerthPosition The berth location of the seat.
Deck Which deck the seat is on.
FacingForward Whether the seat is facing forward.
FareSpaceComfort The space around the seat.
PassengerRph Which passenger the seat is assigned to.
SeatNumber The number of the seat.
SeatPosition The location of the seat.
SpaceType The type of space around the seat.
Status The status of the seat booking.
WagonNumber The number of the wagon the seat is on.
WagonType The type of wagon the seat is on.

Parking Booking Elements

Core Elements - Required

Element Description
ConfirmationNumber The confirmation number from the vendor.
StartDateLocal The starting date of travel for this segment, in the local time of to the starting point. Format: YYYY-MM-DDThh:mm:ss

Core Elements - Optional

Element Description
CancellationNumber The cancellation number from the vendor. This field should be set when you cancel a segment.
ClassOfService The class of the booking.
Currency The 3-letter ISO 4217 currency code for the booking.
DateCancelledUtc The date the booking was cancelled, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateCreatedUtc The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateModifiedUtc The date the booking was modified, in UTC. Format: YYYY-MM-DDThh:mm:ss
EndDateLocal The booking ending time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss
EndDateUtc The booking ending time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss
FrequentTravelerId The traveler’s ID for the frequent traveler reward program.
IsUpgradeAllowed Whether the booking can be upgraded. Format: true/false
Notes Additional information about the booking.
OperatedByVendor The operating vendor of the booking.
ParkingLocationId The location of the parking booking.
PhoneNumber The parking phone number.
Pin The PIN number for the booking.
RateCode The vendor's code for the rate of the booking.
StartAddress The starting address of the booking.
StartAddress2 The starting address of the booking.
StartCity The starting address of the booking.
StartCityCode The IATA airport code for the starting city of the booking.
StartCountry The starting address of the booking.
StartDateUtc The starting date of travel for this segment, in UTC. Format: YYYY-MM-DDThh:mm:ss
StartLocation The parking location.
StartPostalCode The starting address of the booking. Maximum length: 24
StartState The starting address of the booking. Maximum length: 50
Status The booking status.
TimeZone The time zone of the booking. Format: One of the supported Olson or Windows Time Zones.
TotalRate The total rate amount of the booking.
UpgradedDateTime The date and time the booking was upgraded. Format: YYYY-MM-DDThh:mm:ss
Vendor The two letter GDS vendor code.
VendorName The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary.
Charges The charges for this booking. Refer to the Charges Child Elements table.

Travel Booking

NOTE: This booking type is used by the Concur Travel Request product to store the main destination for the trip without specifying a transport type.

Core Elements - Required

Element Description
EndDateLocal The booking ending time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss
StartCity The starting address of the booking.
StartCityCode The IATA airport code for the starting city of the booking.
StartDateLocal The starting date of travel for this segment, in the local time of to the starting point. Format: YYYY-MM-DDThh:mm:ss

Core Elements - Optional

Element Description
CancellationNumber The cancellation number from the vendor. This field should be set when you cancel a segment.
ConfirmationNumber The confirmation number from the vendor.
Currency The 3-letter ISO 4217 currency code for the booking.
DailyRate Average per day rate for the booking. If the rate varies over the duration, it can be specified using the charges model.
DateCancelledUtc The date the booking was cancelled, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateCreatedUtc The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateModifiedUtc The date the booking was modified, in UTC. Format: YYYY-MM-DDThh:mm:ss
EndAddress The ending address of the booking.
EndAddress2 The ending address of the booking.
EndCity The ending address of the booking.
EndCityCode The IATA airport code for the ending city of the booking.
EndCountry The ending address of the booking.
EndDateUtc The booking ending time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss
EndLatitude The latitude for the ending location of the booking.
EndLocation The ending location of the booking.
EndLongitude The longitude of the ending point of the booking.
EndPostalCode The ending address of the booking.
EndState The ending address of the booking.
TransportMode The transport mode of the booking.
Notes Additional information about the booking.
NumPersons The number of persons booked for the trip.
PhoneNumber The parking phone number.
SpecialInstructions The instructions for the booking. Max Length: 256
StartAddress The starting address of the booking.
StartAddress2 The starting address of the booking.
StartCity The starting address of the booking.
StartCityCode The IATA airport code for the starting city of the booking.
StartCountry The starting address of the booking.
StartDateUtc The starting date of travel for this segment, in UTC. Format: YYYY-MM-DDThh:mm:ss
StartLatitude The latitude of the starting location of the booking.
StartLongitude The longitude of the starting location of the booking.
StartPostalCode The starting address of the booking. Maximum length: 24
StartState The starting address of the booking. Maximum length: 50
Status The booking status.
TimeZone The time zone of the booking. Format: One of the supported Olson or Windows Time Zones.
TotalRate The total rate amount of the booking.
Vendor The two letter GDS vendor code.
VendorName The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary.
Charges The charges for this booking. Refer to the Charges Child Elements table.
Seats The seats for the booking. This parent element contains an TravelSeat element for each included seat. The TravelSeat element contains the following child elements:
TravelSeat Elements
Element Description
PassengerRph The passenger assigned to the seat.
SeatNumber The number of the seat.

Charges Child Elements

Core Elements - Required
Percent - The Percent of Fixed Charges

This parent element contains the following child elements:

Element Description
Amount The total amount for the rate for the booking.
Currency The 3-letter ISO 4217 currency code for the total amount.
Description The description for the rate.
IsPaid Whether the rate has been paid. Format: true/false.
IsPrimary Indicates whether the charge is the Primary or Main rate. For example, if one of the rates is the actual rate and the rest are penalties, the actual rate should be set as IsPrimary. Only one charge in a set should be primary. Format: true/false.
SemanticsCode Indicates the charge category for the line item.
SemanticsVendorType The vendor type: H=Hotel, C=Car, A=Air, G=Ground, R=Rail
StartDateLocal The start date of the booking, in the user's local time. Format: YYYY-MM-DDThh:mm:ss
Vendor The vendor for the booking charge.
VendorChargeCode The vendor's code for the charge
Fixed - The Fixed Charges

This parent element contains the following child elements:

Element Description
Currency The 3-letter ISO 4217 currency code for the total amount.
Description The description for the fixed amount.
IsPaid Whether the fixed amount has been paid. Format: true/false.
IsPrimary Whether the fixed amount is primary. Format: true/false.
SemanticsCode Indicates the charge category for the line item. Refer to the Semantics and Vendor Codes document for more information.
SemanticsVendorType The vendor type: H=Hotel, C=Car, A=Air, G=Ground, R=Rail
StartDateLocal The start date of the booking, in the user's local time. Format: YYYY-MM-DDThh:mm:ss
Vendor The vendor applying the booking charge.
VendorChargeCode The vendor's code for the charge.
Rate - The Rate for the Booking

This parent element contains the following child elements:

Element Description
Amount The total amount for the rate for the booking.
Currency The 3-letter ISO 4217 currency code for the total amount.
Description The description for the rate.
IsPaid Whether the rate has been paid. Format: true/false.
IsPrimary Whether the rate is primary. Format: true/false.
NumUnits The number of units expected for the charge. For instance, 3 days
PerUnit The unit of measure for the charge. Values represent rates like per DAY, WEEK, or MONTH
SemanticsCode Indicates the charge category for the line item. Refer to the Semantics and Vendor Codes document for more information.
SemanticsVendorType The vendor type: H=Hotel, C=Car, A=Air, G=Ground, R=Rail
StartDateLocal The start date of the booking, in the user's local time. Format: YYYY-MM-DDThh:mm:ss
Vendor The vendor for the booking charge.
VendorChargeCode The vendor's code for the charge.
RateWithAllowance - The Rate for the Booking, Including any Travel Allowances

This parent element contains the following child elements:

Element Description
AllowanceAmount The cost of overage fees when the allowance is exceeded. For example, if the allowance is 5000 miles, the cost could be $0.02 per mile. The overage must be in the same currency as the basic rate.
AllowanceIsUnlimited Whether the allowance is unlimited. Format: true/false.
AllowanceNumUnits The number of units for the allowance associated with the charge. For example, 5000 miles.
AllowanceUnit The unit of measure for the allowance associated with the charge. For example, a car weekly rate might allow 5000 miles included in the rate.
Amount The total amount for the rate for the booking.
Currency The 3-letter ISO 4217 currency code for the total amount.
Description The description for the rate.
IsPaid Whether the rate has been paid. Format: true/false.
IsPrimary Indicates whether the charge is the Primary or Main rate. For example, if one of the rates is the actual rate and the rest are penalties, the actual rate should be set as IsPrimary. Only one charge in a set should be primary. Format: true/false.
NumUnits The number of units expected for the charge. For instance, 3 days.
PerUnit The unit of measure for the charge. Values represent rates like per DAY, WEEK, or MONTH
SemanticsCode Indicates the charge category for the line item. Refer to the Semantics and Vendor Codes document for more information.
SemanticsVendorType The vendor type: H=Hotel, C=Car, A=Air, G=Ground, R=Rail
StartDateLocal The start date of the booking, in the user's local time. Format: YYYY-MM-DDThh:mm:ss
Vendor The vendor for the booking charge.
VendorChargeCode The vendor's code for the charge.

Time Zone Formats

Olson Time Zones

Africa/Cairo Africa/Casablanca Africa/Harare Africa/Luanda
Africa/Nairobi Africa/Windhoek America/Anchorage America/Argentina/Buenos_Aires
America/Asuncion America/Bahia America/Bogota America/Buenos_Aires
America/Caracas America/Chicago America/Chihuahua America/Denver
America/Godthab America/Guyana America/Halifax America/Indianapolis
America/Los_Angeles America/Manaus America/Mexico_City America/Montevideo
America/New_York America/Phoenix America/Regina America/Santiago
America/Sao_Paulo America/St_Johns America/Swift_Current America/Tijuana
Asia/Almaty Asia/Amman Asia/Baghdad Asia/Baku
Asia/Bangkok Asia/Beirut Asia/Calcutta Asia/Colombo
Asia/Damascus Asia/Dhaka Asia/Irkutsk Asia/Jerusalem
Asia/Kabul Asia/Kamchatka Asia/Karachi Asia/Karachi
Asia/Katmandu Asia/Krasnoyarsk Asia/Magadan Asia/Muscat
Asia/Novosibirsk Asia/Rangoon Asia/Riyadh Asia/Seoul
Asia/Shanghai Asia/Singapore Asia/Taipei Asia/Tbilisi
Asia/Tehran Asia/Tokyo Asia/Ulaanbaatar Asia/Vladivostok
Asia/Yakutsk Asia/Yekaterinburg Asia/Yerevan Atlantic/Azores
Atlantic/Cape_Verde Atlantic/South_Georgia Australia/Adelaide Australia/Brisbane
Australia/Darwin Australia/Hobart Australia/Perth Australia/Sydney
Etc/GMT+12 Etc/GMT-11 Etc/GMT-2 Europe/Athens
Europe/Berlin Europe/Helsinki Europe/Istanbul Europe/Kaliningrad
Europe/London Europe/Minsk Europe/Moscow Europe/Paris
Europe/Prague Europe/Sarajevo GMT GMT-1200
Indian/Mauritius Pacific/Apia Pacific/Auckland Pacific/Fiji
Pacific/Guadalcanal Pacific/Guam Pacific/Honolulu Pacific/Tongatapu
UTC

Windows Time Zones

Africa/Cairo Africa/Casablanca Africa/Harare Africa/Luanda
Africa/Nairobi Africa/Windhoek America/Anchorage America/Argentina/Buenos_Aires
America/Asuncion America/Bahia America/Bogota America/Buenos_Aires
America/Caracas America/Chicago America/Chihuahua America/Denver
America/Godthab America/Guyana America/Halifax America/Indianapolis
America/Los_Angeles America/Manaus America/Mexico_City America/Montevideo
America/New_York America/Phoenix America/Regina America/Santiago
America/Sao_Paulo America/St_Johns America/Swift_Current America/Tijuana
Asia/Almaty Asia/Amman Asia/Baghdad Asia/Baku
Asia/Bangkok Asia/Beirut Asia/Calcutta Asia/Colombo
Asia/Damascus Asia/Dhaka Asia/Irkutsk Asia/Jerusalem
Asia/Kabul Asia/Kamchatka Asia/Karachi Asia/Karachi
Asia/Katmandu Asia/Krasnoyarsk Asia/Magadan Asia/Muscat
Asia/Novosibirsk Asia/Rangoon Asia/Riyadh Asia/Seoul
Asia/Shanghai Asia/Singapore Asia/Taipei Asia/Tbilisi
Asia/Tehran Asia/Tokyo Asia/Ulaanbaatar Asia/Vladivostok
Asia/Yakutsk Asia/Yekaterinburg Asia/Yerevan Atlantic/Azores
Atlantic/Cape_Verde Atlantic/South_Georgia Australia/Adelaide Australia/Brisbane
Australia/Darwin Australia/Hobart Australia/Perth Australia/Sydney
Etc/GMT+12 Etc/GMT-11 Etc/GMT-2 Europe/Athens
Europe/Berlin Europe/Helsinki Europe/Istanbul Europe/Kaliningrad
Europe/London Europe/Minsk Europe/Moscow Europe/Paris
Europe/Prague Europe/Sarajevo GMT GMT-1200
Indian/Mauritius Pacific/Apia Pacific/Auckland Pacific/Fiji
Pacific/Guadalcanal Pacific/Guam Pacific/Honolulu Pacific/Tongatapu
UTC

Itinerary Service

Overview

The Itinerary API can be used to programmatically access travel data such as trips and bookings in Concur Travel. Concur Travel uses this data to match and consolidate bookings it receives from disparate sources and put these into consolidated travelers’ itineraries, providing travelers a convenient way to view their trips in a single itinerary view. Travelers can view their itineraries through mobile applications or other services.

Version

Version 1.0

Resources

Trip

Booking

Concepts

Itineraries and Trips

The terms itinerary and trip are synonyms. Trip is the name used for the SAP Concur web service resource that represents an itinerary.

Itinerary, Booking Record, and Segment

Who Can Use This Web Service?

TripLink suppliers, travel management companies (TMCs), and SAP Concur clients and third-party developers can use the Itinerary API. The level of access to the data in the Concur Travel system depends on who is accessing it and the SAP Concur products that have been purchased.

Travel Management Companies

SAP Concur Clients and Third-Party Developers

SAP Concur products are highly configurable, and not all clients will have access to all features. Some itinerary data may have come from Sabre. SAP Concur encourages you to speak to Sabre about becoming a Sabre Authorized Developer.

Authentication and Authorization

The Itinerary API uses OAuth 2.0 for authenticating users and authorizing access to travel data.

Authorization for TMCs

TMCs can request or send travel bookings in two ways:

The travel supplier can request or send travel bookings by using an OAuth token for the user the travel booking belongs to, generated with the user's involvement.

Configuration

FAQs

When Do I Send Trips Versus Bookings?

The Itinerary API returns the full booking details to the supplier who will provide the booked service. Suppliers that are not the service provider will receive a subset of the possible fields. These vary by the type of booking relative to the type of supplier. For example, Air booking suppliers that are not the supplier will not see the following fields:

How Can We Save Additional Charges for Hotel and Car Segments? What Types of Charges Are Supported?

The Charges element under Car and Hotel segments allow you to save additional charges using Semantics Codes. Refer to the Semantics and Vendor Codes sections under Reference for more information.

What Vendor Codes Can I Use When Sending Hotel and Car Segments?

Refer to the Semantics and Vendor Codes sections for the full list.

Can I View a Trip Posted Through the Itinerary API in the SAP Concur UI?

Yes. The user who owns the trip will see the trip on their home page. If the trip is in the future, it will show under the upcoming trip list. Trips that are ready to expense will show in the expense report list.

When Can a Trip Be Expensed?

Trips can be expensed after the trip is over under the following conditions:

Air segments can be expensed as soon as they have a ticket with a valid coupon, if the company uses the PreExpenseAir option.

Why is My New Booking Not Showing in the UI?

The request returned successfully with HTTP status - 200 OK. Posted bookings are automatically merged with any existing trip with overlapping dates. Most likely, a trip exists with the same dates and the booking has been added to it.

Will Posted Bookings Be Overwritten by Emailed or TripIt Trips?

No.

Will Posted Bookings Merge with Existing Cliqbook or TripIt Trips?

Yes.

Will Posted Trips Merge with Existing Trips?

No.

Best Practices

Reference

The Itinerary Reference documentation includes the following reference information that can be used in conjunction with the Trip Resource API and Booking Resource API documentation. It includes the following reference topics:

Itinerary Data Model

The Itinerary data model defines data elements that are returned or sent when getting, creating, updating, or deleting trips and bookings with the /api/travel/trip/v1.1 and /api/travel/booking/v1.1 resources respectively.

Trips include all bookings in an itinerary whereas a booking includes only a specific segment of an itinerary. It includes the following elements:

Root Elements

Element Name Data Type TripLink Description
id String Y The unique identifier for the trip URI with encrypted ID.
ItineraryInfo Y Parent element with the information about an itinerary for the specified user.
TripId String Y Encrypted trip identifier value.
ItinLocator String Y This element is obsolete and is supported only for backward compatibility.
BookedVia String The booking method for the trip.
BookedByFirstName String Y The first name of the person who booked the trip.
BookedByLastName String Y The last name of the person who booked the trip.
HasOpenBookingPassive String
CancelComments String Y The comments provided if the itinerary is cancelled. Maximum length: 256 characters.
ClientLocator String
TripLinkLocator String
Comments String Y (Description here). Maximum length 512 characters.
DateBookedLocal DateTime Y The date the trip was booked, in the local time of the booking location. Format: YYYY-MM-DDThh:mm:ss
DateCreatedUtc DateTime Y The date that this trip was created, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateModifiedUtc DateTime Y The date when this trip was last modified in UTC format. Format: YYYY-MM-DDThh:mm:ss.
Description String Y The description for this trip. Maximum length 512 characters.
EndDateLocal DateTime Y The end date of the trip in the ending location’s timezone. Format: YYYY-MM-DDThh:mm:ss.
EndDateUtc DateTime Y The end date of the trip, in UTC. Format: YYYY-MM-DDThh:mm:ss
TravelRequestId String
IsPersonal Boolean Y Indicates whether this trip is for business or for leisure. Format: Business, Leisure
ProjectName String The name of the project assiciated with this trip. Maximum length 255 characters.
StartDateLocal DateTime Y The start date of the trip in the starting location’s timezone. Format: YYYY-MM-DDThh:mm:ss.
StartDateUtc DateTime Y The date when this trip started in UTC format. Format: YYYY-MM-DDThh:mm:ss.
TripName String Y Name of the trip. Maximum length 255 characters.
TripStatus unsignedByte Y The status of the trip. This element only appears if the includeCanceledTrips query parameter is used in the request.
UserLoginId Y The user's login to SAP Concur. This element appears only when the OAuth token is associated with a SAP Concur account with one of these roles: Web Services Administrator for Professional or Can Administer for Standard.
Bookings Array Y An array of bookings that contains a Booking child element for each included booking.
Custom Attributes Array
RuleViolations Array N The list of rule violations associated with the itinerary. This parent element contains a RuleViolation child element for each associated rule violation.

Booking Elements

The Bookings parent element contains a Booking child element for each included booking. TripLink suppliers have access only to a subset of the Booking elements. The TripLink column indicates with a Y if a specific element is available for a TripLink supplier. Each booking element contains the following child elements:

Element Data Type TripLink Description
BookingOwner String Y Specifies the tool that supplied the booking to Concur Travel. The possible values are: ConcurTravel, OpenBookingEmail, AmadeusETravel, ConcurConnectAPI, OpenBookingSupplier and TripIt
BookingSource String Y For TMCs: The name of the booking source for this booking. A booking source is a textual name the system uses to track where a booking took place.
For TripLink suppliers: The name of the booking source for this booking. A booking source is a textual name the system uses to track where a booking took place. This could be a GDS, OTA, Vendor Code for Supplier website or Supplier Direct Connect API
Source Y This element is obsolete and is supported only for backward compatibility.
DateBookedLocal DateTime Y The date the booking was created, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss
DateCreatedUtc DateTime Y The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateModifiedUtc DateTime Y The date the booking was last modified, in UTC. Format: YYYY-MM-DDThh:mm:ss
FareExpiresEmailDatetimeUtc DateTime
FormOfPaymentName String The name of the form of payment for the booking.
FormOfPaymentType String The type of the form of payment.
LastTicketDateUtc DateTime
PassengerCount Int The total count of passengers for the booking.
RecordLocator String Y The unique identifier for the booking
RetrievedDateUtc
TicketMailingAddress The mailing address for the booked ticket, if available.
TicketPickupLocation The pickup location for the booked ticket, if available
TicketPickupNumber The confirmation number to pick up the booked ticket, if available.
CreditCardType String The type of credit card (for example, Visa/Mastercard/etc.).
CreditCardLastFour String The last four digits of credit card number.
AirfareQuotes Array List of stored airfare quotes for this booking. For more information, see the AirFareQuotes Elements table.
ItinSourceName String The itinerary source. Format: TravelSupplier
AirlineTickets Array List of airline tickets for this booking. For more information, see the AirLine Tickets Elements table.
Charges Array The charges for this booking. For more information, see the Charges Elements table later on this page.
MiscChargeOrders Array An array of miscellaneous charge orders for this booking. This parent element has a MiscellaneousChargeOrders child element for each miscellaneous charge order associated with this booking. For information about the child elements, see the MiscellaneousChargeOrders Elements table later on this page.
Passengers Array Y This parent element contains a Passenger child element for each booked passenger. See the Passengers Elements table for more information about the child elements.
PassPrograms List of Pass Programs for this booking. This parent element has a PassProgram child element for each pass program associated with the booking. For information about the child elements, see the PassProgram Elements table later on this page.
PhoneNumbers List of Phone numbers associated with this booking. This parent element has a PhoneNumberData child element for each phone number associated with the booking. For information about the child elements, see the PhoneNumberData Elements table later on this page.
RailPayments Array List of Rail payments associated with rail segments in this booking. For information about the child elements in the array, see the RailPayments Elements table later on this page.
Segments Y List of Segments in this booking. This parent element contains one or more Air, Car, Hotel, Dining, Ride, Rail, Parking, or Travel parent elements for the booking. The segments are described in the tables below, see Air Booking Elements, Car Booking Elements, Hotel Booking Elements, Dining Booking Elements, Ride Booking Elements, Parking Booking Elements, and Travel Booking Elements.
Delivery String The method this booking was delivered.
WaitListSegments The segments that the traveler is waitlisted for this booking.
Warnings The warnings associated with the booking.
WebAddresses List of web addresses such as emails and pickup URLs associated with this booking.
MiscellaneousChargeOrder Elements
Element Name Data Type TripLink Description
DateCreatedUtc dateTime The date the charge order was created, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateModifiedUtc dateTime The date the charge order was last modified, in UTC. Format: YYYY-MM-DDThh:mm:ss
IssueDate dateTime The date the charge order was issued. Format: YYYY-MM-DDThh:mm:ss
PlatingCarrierNumericCode string Part of the ticket number that indicates the airline code. This is a three digit number. For example: 001=American, 005=Continental, 006=Delta, 012=Northwest
PlatingControlNumber string Part of the ticket number that indicates the ticket control number. Format: Ten digit number.
TotalAmount decimal The total amount of charge orders for the ticket.
TotalAmountCurrency string The 3-letter ISO 4217 currency code for the total charge order amount.
PassProgram Elements
Element Name Data Type TripLink Description
Amount decimal The program amount.
Name string The program name.
Type string The program type.
UserFirstName string The first name of the passenger.
UserLastName string The last name of the passenger.
PhoneNumberData Elements
Element Name Data Type TripLink Description
PassengerRPH integer Indicates the passenger to whom this phone number belongs.
PhoneNumber string The passenger's phone number.
Type string The type of phone number.
Description string The description for the phone number.
RailPayments Elements
Element Name Data Type TripLink Description
RailAdjustment Type The amount adjusted for a rail booking. For information about the RailAdjustment child elements, see the RailAdjustment Elements table later on this page.
RailPayment Type The payment information for a rail booking. For information about the RailPayment child elements, see the RailPayment Elements table later on this page.
RailAdjustment Elements
Element Name Data Type TripLink Description
AdjustmentDateTime dateTime
AdjustmentDateTimeUTC dateTime
AdjustmentType string
DateCreatedUtc dateTime
DateModifiedUtc dateTime
TicketDocumentIdentifier string
TotalAdjustment decimal
TotalAdjustmentCurrency string
Taxes Array This parent element contains a Tax child element for each rail adjustment tax. For more information, see the Tax Elements table later on this page.
RailPayment Elements
Element Name Data Type TripLink Description
BaseFare decimal The base fare of the booking quote.
BaseFareCurrency string The 3-letter ISO 4217 currency code for the total fare.
DateCreatedUtc dateTime The date the quote was created, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateModifiedUtc dateTime The date the quote was last modified, in UTC. Format: YYYY-MM-DDThh:mm:ss
IssueByDate dateTime The date the quote must be issued by. Format: YYYY-MM-DDThh:mm:ss
IssueDateTime dateTime
IssueDateTimeUTC dateTime
TicketDocumentIdentifier string
TicketType string
TotalFare decimal The total price of the booking.
TotalFareCurrency string The 3-letter ISO 4217 currency code for the total fare.
RailCharges array The charges applied by the airline. This parent element contains a Fixed and a Tax child element for each fixed charge and tax from the airline. See the Fixed Elements table and the Tax Elements table.

AirfareQuotes Elements

The AirfareQuotes parent element is an array that contains a Quote child element that contains the following child elements.

Element Name Data Type TripLink Description
BaseFare Decimal
BaseFareCurrency String
BaseFareNuc Decimal
BaseFareNucCurrency String
DateCreatedUtc DateTime
DateModifiedUtc DateTime
Endorsements String
IssueByDate DateTime
TotalFare Decimal
TotalFareCurrency String
AirlineCharges Array This parent element contains a Fixed and a Percent child element for each fixed charge and percent of fixed charge associated with this airfare quote. For information about these child elements, see the Fixed Elements table and the Percent Elements table later on this page.

Passengers Elements

The passenger parent element is the Passengers Element in Booking Elements. This parent element contains a Passenger child element for each booked passenger.

Element Name Data Type Required/Optional TripLink Description
NameFirst String required Y The first name of the passenger.
NameLast String required Y The last name of the passenger.
NameMiddle String optional Y The middle name of the passenger.
NamePrefix String optional Y The name prefix of the passenger.
NameRemark String optional Y Additional details about the passenger's name.
NameSuffix String optional Y The name suffix of the passenger.
NameTitle String optional Y The title of the passenger.
TextName String optional Y The user's full name as entered in the booking tool if different from the name in the database.
FrequentTravelerProgram String optional Y Passenger's loyalty programs

AirlineTickets Elements

The AirlineTickets parent element is an array that contains the following child elements.

Element Name Data Type TripLink Description
AirlineAdjustmentType Type Any adjustment made to the booking. For information about the child elements of AirlineAdjustmentType, see the AirlineAdjustmentType Elements table later on this page.
ManualAirlineTicket Type The manual airline ticket for the booking. For information about the child elements of ManualAirlineTicket, see the ManualAirlineTicket Elements table later on this page.
AirlineTicket Type The airline ticket for the booking. For information about the child elements of AirlineTicket, see the AirlineTicket Elements table later on this page.
AirlineAdjustmentType Elements
Element Name Data Type TripLink Description
AddCollectAmount decimal
AdjustmentDateTime dateTime
AdjustmentDateTimeUTC dateTime
AdjustmentType String
DateCreatedUtc dateTime
DateModifiedUtc dateTime
PassengerName string
PlatingCarrierNumericCode string
PlatingControlNumber string
RecordLocator string
TotalAdjustment decimal
TotalAdjustmentCurrency string
Taxes Array
ManualAirlineTicket Elements
Element Name Data Type TripLink Description
BaseFare decimal
BaseFareCurrency string
DateCreatedUtc dateTime
DateModifiedUtc dateTime
TotalFareTotalFareCurrency decimal
AirlineCharges array The charges applied by the airline. This parent element contains a Fixed and a Tax child element for each fixed charge and tax from the airline. For information about these child elements, see the Fixed Elements table and the Tax Elements table later on this page.
AirlineTicket Elements
Element Name Data Type TripLink Description
AddCollectAmount decimal
AccountingLine string
BaseFare decimal
BaseFareCurrency string
BaseFareNuc decimal
BaseFareNucCurrency string
ComparisonFare decimal
ComparisonFareCurrency string
DateCreatedUtc dateTime
DateModifiedUtc dateTime
Endorsements string
InvoiceNumber string
IssueDateTime dateTime
IssueDateTimeUTC dateTime
IssuingIataAgencyNumber integer
IssuingPseudoCity string
LinearFareConstructor string
MasterTicketNumber string
NameReference string
PassengerName string
PlatingCarrierNumericCode string
PlatingControlNumber string
ProgramCarrierCode string
ProgramMembershipNumber string
RecordLocator string string
SabreDkNumber string string
Ticketless boolean
TicketType string
TotalFare decimal
TotalFareCurrency string
TourIdentifier string
AirlineCharges array A list of airline charges for this ticket. This parent element contains a Fixed child element for each fixed charge from the airline. For information about these child elements, see the Fixed Elements table later on this page.
AirlineTicketCoupons array A list of coupons for this ticket. This parent element has an AirlineTicketCoupon child element for each coupon associated with this airline ticket. For information about these child elements, see the AirlineTicketCoupon Elements table later on this page.
AirlineTicketExchanges array A list of exchanges for this ticket. This parent element has an AirlineTicketExchange child element for each exchange associated with this airline ticket. For information about these child elements, see the AirlineTicketExchange Elements table later on this page.
AirlineTicketFareBreakups array A list of fare breakups for this ticket. This parent element has an AirlineTicketFareBreakup child element for each fare breakup associated with this airline ticket. For information about these child elements, see the AirlineTicketFareBreakup Elements table later on this page.
AirlineTicketCoupons Elements
Element Name Data Type TripLink Description
ClassOfService string
CouponNumber unsignedByte
CouponStatus string
EndCityCode string
FlightNumber string
NotValidAfterDate dateTime
NotValidBeforeDate dateTime
RateCode string
StartCityCode sring
StartDateLocal dateTime
Status string
TicketDesignator string
Vendor string
AirlineTicketExchanges Elements
Element Name Data Type TripLink Description
Amount decimal
AppliedSegment1 unsignedByte
AppliedSegment10 unsignedByte
AppliedSegment2 unsignedByte
AppliedSegment3 unsignedByte
AppliedSegment4 unsignedByte
AppliedSegment5 unsignedByte
AppliedSegment6 unsignedByte
AppliedSegment7 unsignedByte
AppliedSegment8 unsignedByte
AppliedSegment9 unsignedByte
Currency string
OldRecordLocator string
DateModifiedUtc dateTime
PlatingCarrierNumericCode string
PlatingControlNumber string
AirlineTicketFareBreakups Elements
Element Name Data Type TripLink Description
BaseFare decimal
BaseFareCurrency sring
DateCreatedUtc dateTime
DateModifiedUtc dateTime
IssueByDate dateTime
IssueDateTime dateTime
IssueDateTimeUTC dateTime
TicketDocumentIdentifier string
TicketType string
TotalFare decimal
TotalFareCurrency string
Taxes array The charges applied by the airline. This parent element contains a Fixed and a Tax child element for each fixed charge and tax from the airline. For more information, see the Fixed Elements table and the Tax Elements table later on this page.
Fixed Elements

The Fixed element contains the following child elements.

Element Name Data Type TripLink Description
Amount Decimal The total amount for the rate for the booking.
Currency String The 3-letter ISO 4217 currency code for the total amount.
Description String The description for the rate.
IsPaid Boolean Whether the rate has been paid. Format: true/false.
IsPrimary Boolean Indicates whether the charge is the Primary or Main rate. For example, if one of the rates is the actual rate and the rest are penalties, the actual rate should be set as IsPrimary. Only one charge in a set should be primary. Format: true/false.
SemanticsCode String Indicates the charge category for the line item. Refer to the Semantics Codes table for more information.
SemanticsVendorType String The vendor type: H=Hotel, C=Car, A=Air, G=Ground, R=Rail
StartDateLocal DateTime The start date of the booking, in the user's local time. Format: YYYY-MM-DDThh:mm:ss
Vendor String The vendor for the booking charge.
VendorChargeCode String The vendor's code for the charge
Tax Elements

This Tax element contains the following child elements.

Element Name Data Type TripLink Description
TaxAmount Decimal The amount of the tax.
TaxType String The type of the tax.
Percent Elements

The percent of fixed charges. This parent element contains the following child elements:

Element Data Type TripLink Description
Amount Decimal The total amount for the rate for the booking.
Currency string The 3-letter ISO 4217 currency code for the total amount.
Description sring The description for the rate.
IsPaid boolean Whether the rate has been paid. Format: true/false.
IsPrimary boolean Indicates whether the charge is the Primary or Main rate. For example, if one of the rates is the actual rate and the rest are penalties, the actual rate should be set as IsPrimary. Only one charge in a set should be primary. Format: true/false.
SemanticsCode string Indicates the charge category for the line item. Refer to the Semantics Codes table for more information.
SemanticsVendorType string The vendor type: H=Hotel, C=Car, A=Air, G=Ground, R=Rail
StartDateLocal dateTime The start date of the booking, in the user's local time. Format: YYYY-MM-DDThh:mm:ss
Vendor string The vendor for the booking charge.
VendorChargeCode string The vendor's code for the charge
CustomAttributes Elements

The CustomAttributes parent element contains a CustomAttribute child element with the following child elements.

Element Name Data Type TripLink Description
Data String
DisplayTitle String
DisplayValue String
Name String
DataType String
DisplayOnItinerary Boolean
ExternalId Int
RuleViolations Elements

The RuleViolations element contains a list of rule violations associated with the itinerary. This parent element contains a RuleViolation child element for each associated rule violation. The RuleViolation element has the following child elements:

Element Name Data Type TripLink Description
BestGdsPrice Decimal
BestGdsVendor String
BestInternetPrice Decimal
BestInternetVendor String
CompanyReasonCode String
CompanyRuleText String
Currency String
DateEntered DateTime
EndCity String
EndDate DateTime
NumberOfStops Int
QuotedPrice Decimal
RuleAction String
RuleName String
SegmentType String
SelectedOtherAmount Decimal
SelectedOtherAmountType String
StartCity String
StartDate DateTime
TariffPrice Decimal
TravelerComments String
VendorCode String
VendorName String

AirBooking Elements

The Air Booking parent element is the Air Element in the Segments Array in Booking Elements. This parent element contains an Air Booking child element for each booked flight.

Element Data Type TripLink Description
ClassOfService string The class of the booking.
ConfirmationNumber string The record locator or confirmation number for the flight from the airline.
EndCityCode string Y The IATA airport code for the end city of the booking.
EndDateLocal dateTime Y The booking ending time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss.
For TripLink suppliers: The time portion of this value will be set to T00:00:00 if the request is from a TripLink - Open Booking Air supplier that does not own the booking.
FlightNumber string Y The flight number for the booking.
StartCityCode string Y The IATA airport code for the starting address for the booking.
StartDateLocal dateTime Y The booking starting time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss.
For TripLink suppliers: The time portion of this value will be set to T00:00:00 if the request is from a TripLink - Open Booking Air supplier that does not own the booking.
Vendor string Y
CancellationNumber string The cancellation number from the vendor. This field should be set when you cancel a segment.
CancellationPolicy string The cancellation policy from the vendor.
Charges Parent Element The charges for this booking. For more information, see the Charges Elements table later on this page.
DateCancelledUtc dateTime The date the booking was cancelled, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateCreatedUtc dateTime The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateModifiedUtc dateTime The date the booking was modified, in UTC. Format: YYYY-MM-DDThh:mm:ss
EndDateUtc dateTime Y The booking ending time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss.
For TripLink suppliers: The time portion of this value will be set to T00:00:00 if the request is from a TripLink - Open Booking Air supplier that does not own the booking.
EndGate string Y The arrival gate for the booking.
For TripLink suppliers: Will not appear in the response if the request is from a TripLink - Open Booking Air supplier that does not own the booking.
EndTerminal string Y The arrival terminal for the booking.
For TripLink suppliers: Will not appear in the response if the request is from a TripLink - Open Booking Air supplier that does not own the booking.
LegId string The leg ID of the booking. Leg IDs do not change on a connection. For each unique leg ID in the trip, all flights subsequent to the first segment with the same leg ID are connections.
Seats Parent Element The seats for the booking. This parent element contains an AirSeat element for each included seat. For more information, see the AirSeat Elements table later on this page.
StartDateUtc dateTime Y The booking starting time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss.
For TripLink suppliers:The time portion of this value will be set to T00:00:00 if the request is from a TripLink - Open Booking Air supplier that does not own the booking.
StartGate string Y The departure gate for the booking.
For TripLink suppliers: Will not appear in the response if the request is from a TripLink - Open Booking Air supplier that does not own the booking.
StartTerminal string Y The departure terminal for the booking.
For TripLink suppliers: Will not appear in the response if the request is from a TripLink - Open Booking Air supplier that does not own the booking.
Status string The GDS based booking status for the segment such as HK, HL, BK, etc.
TimeZone string Y The time zone of the booking. Format: One of the supported Olson or Windows Time Zones.
AircraftCode string The code for the aircraft type.
Bags string The number of bags included in the booking.
Cabin string The section of the airplane for the booking.
CarbonEmissionLbs decimal The pounds of carbon emission for this booking.
CarbonModel integer The model used to calculate the carbon emissions.
CheckedBaggage string Whether the booking includes checked baggage.
Duration integer The duration of the booked flight.
ETicket string Whether the booking has an e-ticket. Format: Y/N
IsOpenSegment boolean Whether the segment is open. Format: True/False
IsPreferredVendor integer If the airline is marked as a preferred property by the company. Format: True/False
CreditCardType String The type of credit card (for example, Visa/Mastercard/etc.).
CreditCardLastFour String The last four digits of credit card number.
IsUpgradeAllowed boolean Whether the booking can be upgraded. Format: True/False
Meals string The meals included in the booking.
Miles integer The number of miles included in the booking.
Notes string Additional details about the booking.
OpenSegment string Additional information about the open segment.
OperatedByFlightNumber string Flight Number provided by the airline operating the flight on behalf of the booked airline.
OperatedByVendor sring The airline operating the flight on behalf of the booked airline.
OperatedByVendorName string The name of the airline operating the flight on behalf of the booked airline.
Services string The services included in the booking.
SpecialInstructions string Additional instructions regarding the booking. Max Length: 256
UpgradedDateTime dateTime The date and time the booking was upgraded. Format: YYYY-MM-DDThh:mm:ss
AirSeat Elements
Element Data Type Description
PassengerRph integer The passenger assigned to the seat.
SeatNumber string The number of the seat.

CarBooking Elements

The Car Booking parent element is the Car Element in the Segments Array in Booking Elements. This parent element contains a Car Booking child element for each booked car.

Element Data Type TripLink Description
ConfirmationNumber string The confirmation number from the vendor.
EndDateLocal dateTime Y The booking ending time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss
StartDateLocal dateTime Y The booking starting time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss
Vendor string The two letter GDS vendor code. See the Car Vendor Codes table for car vendor codes.
CancellationNumber string The cancellation number from the vendor. This field should be set when you cancel a segment.
CancellationPolicy string The cancellation policy from the vendor.
Charges Parent Element The charges for this booking. For more information, see the Charges Elements table.
Currency string The 3-letter ISO 4217 currency code for the booking.
DailyRate decimal The daily rate for the booking.
DateCancelledUtc dateTime The date the booking was cancelled, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateCreatedUtc dateTime The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateModifiedUtc dateTime The date the booking was modified, in UTC. Format: YYYY-MM-DDThh:mm:ss
EndCityCode string Y The IATA airport code for the ending address for the booking.
EndDateUtc dateTime Y The booking ending time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss
EndLatitude string The latitude for the ending location of the booking.
EndLongitude string The longitude for the ending location of the booking.
Notes string Additional information about the booking.
PhoneNumber string The phone number for the user.
RateCode string The rate code for the booking.
StartCityCode string Y The IATA airport code for the starting address for the booking.
StartDateUtc dateTime Y The booking starting time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss
StartLatitude string The latitude for the starting location of the booking.
StartLongitude string The longitude for the starting location of the booking.
Status string The booking status.
TimeZone string Y The time zone of the booking. Format: One of the supported Olson or Windows Time Zones.
TotalRate decimal The total rate amount of the booking.
VendorName string The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary.
AirCondition string The character code that indicates if car has air conditioner. R for AC, N for No AC
Body string The character code to indicate how many passengers the car can seat. B for 2-door, D for 4-door, F for Four-wheel drive, J for All Terrain, K for truck, L for Limo, P for pick-up, R for recreation, S for Sport, T for Convertible, V for Van, W for Wagon/Estate, X for special.
Class string Character code to indicate the class of the car (for example, if it is economy, full size, compact, etc.). Varies by Vendor. C for compact, E for economy, F for full size, I for Intermediate, L for Luxury, M for Mini, P for Premium, S for Standard, X for special.
DiscountCode string The discount code used by the company/TMC to get a discounted rate.
CreditCardType String The type of credit card (for example, Visa/Mastercard/etc.).
CreditCardLastFour String The last four digits of credit card number.
DropoffCollectionAddress1 string The AddressLine1 for the dropoff address when the rental service offers dropoff.
DropoffCollectionAddressType string
DropoffCollectionCategory string
DropoffCollectionCity string City for the dropoff address when the rental service offers dropoff.
DropoffCollectionCityCode string The IATA airport code for the dropoff address when the rental service offers dropoff.
DropoffCollectionCountry string The country for the dropoff address when the rental service offers dropoff.
DropoffCollectionLatitude string The latitude for the dropoff address when the rental service offers dropoff.
DropoffCollectionLongitude string The longitude for the dropoff address when the rental service offers dropoff.
DropoffCollectionNumber string
DropoffCollectionPhoneNumber string The phone number for the dropoff address when the rental service offers dropoff.
DropoffCollectionPostalCode string The postal code for the dropoff address when the rental service offers dropoff.
DropoffCollectionState string The state for the dropoff address when the rental service offers dropoff.
EndAddress string The ending address for the booking.
EndAddress2 string The ending address for the booking.
EndCity string Y The ending address for the booking.
EndCloseTime string The closing time for the dropoff location.
EndCountry string Y The ending address for the booking.
EndLocation string The dropoff location.
EndOpenTime string The opening time of the dropoff location.
EndPhoneNumber string The phone number of the dropoff location.
EndPostalCode string The ending address for the booking.
EndState string Y The ending address for the booking.
FrequentTravelerId string The loyalty program ID for the user.
IsUpgradeAllowed boolean Whether the booking can be upgraded. Format: True/False
NumCars unsignedByte The number of cars rented.
NumPersons unsignedByte The number of people including the driver that the rental is for.
PickupDeliveryAddress1 string The AddressLine1 for the pickup address when the rental service offers pickup.
PickupDeliveryAddressType string
PickupDeliveryCategory string
PickupDeliveryCity string The city for the pickup address when the rental service offers pickup.
PickupDeliveryCityCode string The IATA airport code for the pickup address when the rental service offers pickup.
PickupDeliveryCountry string The country for the pickup address when the rental service offers pickup.
PickupDeliveryLatitude string The latitude for the pickup address when the rental service offers pickup.
PickupDeliveryLongitude string The longitude for the pickup address when the rental service offers pickup.
PickupDeliveryNumber string
PickupDeliveryPhoneNumber string The phone number for the pickup address when the rental service offers pickup.
PickupDeliveryPostalCode string The postal code for the pickup address when the rental service offers pickup.
PickupDeliveryState string The state for the pickup address when the rental service offers pickup.
RateType string The rate type for the booking.
SpecialEquipment string Any special equipment required by the renter.
SpecialInstructions string Additional instructions regarding the booking. Max Length: 256
StartAddress string The starting address of the booking.
StartAddress2 string The starting address for the booking.
StartCity string Y The starting address for the booking.
StartCloseTime string The closing time for the pickup location.
StartCountry string Y The starting address for the booking.
StartLocation string The starting location of the booking.
StartOpenTime string The opening time for the pickup location.
StartPostalCode string The starting address for the booking.
StartState string Y The starting address for the booking.
Transmission string The character code that indicates if the car has auto-transmission. A for Auto, M for Manual
UpgradedDateTime dateTime The date and time the booking was upgraded. Format: YYYY-MM-DDThh:mm:ss

Hotel Booking Elements

The Hotel Booking parent element is the Hotel Element in the Segments Array in Booking Elements. This parent element contains a Hotel Booking child element for each booked hotel.

Element Data Type TripLink Description
ConfirmationNumber string The confirmation number from the vendor.
EndDateLocal dateTime Y The booking ending time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss
Name string The hotel name for the booking.
StartCityCode string Y The IATA airport code for the starting address for the booking.
StartDateLocal dateTime Y The booking starting time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss
Status string Y The booking status.
Vendor string The two letter GDS vendor code. See the Hotel Codes table for hotel vendor codes.
CancellationNumber string The cancellation number from the vendor. This field should be set when you cancel a segment.
CancellationPolicy string The cancellation policy from the vendor.
Charges Parent Element The charges for this booking. For more information, see the Charges Elements table.
CheckinTime string The check in time for the hotel booking.
CheckoutTime string The check out time for the hotel booking.
Currency string The 3-letter ISO 4217 currency code for the booking.
CreditCardType String The type of credit card (for example, Visa/Mastercard/etc.).
CreditCardLastFour String The last four digits of credit card number.
DailyRate decimal Average per day rate for the hotel. If the rate varies over the duration, it can be specified using the charges model.
DateCancelledUtc dateTime The date the booking was cancelled, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateCreatedUtc dateTime Y The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateModifiedUtc dateTime Y The date the booking was modified, in UTC. Format: YYYY-MM-DDThh:mm:ss
EndDateUtc dateTime Y The booking ending time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss
HotelPropertyId string The hotel's property ID.
Notes string Additional information about the booking.
NumPersons unsignedByte The number of people the booking is for.
NumRooms unsignedByte The number of rooms the booking is for.
PhoneNumber string The phone number for the booking.
RateCode string The rate code for the booking.
RoomDescription string The room description for the booking. Max Length: 200
RoomType string The room type for the booking.
SpecialInstructions string Additional instructions regarding the booking. Max Length: 256
StartAddress string The starting address of the booking.
StartAddress2 string The starting address for the booking.
StartCity string Y The starting address for the booking.
StartCountry string Y The starting address for the booking.
StartLatitude string The latitude for the starting location of the booking.
StartLongitude string The longitude for the starting location of the booking.
StartPostalCode string The starting address for the booking.
StartState string The starting address for the booking.
StartDateUtc dateTime Y The booking starting time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss
TimeZone string Y The time zone of the booking. Format: One of the supported Olson or Windows Time Zones.
TotalRate string The total rate amount of the booking.
EndCityCode string The IATA airport code for the ending address for the booking.
DiscountCode string The discount code for the booking.
FrequentTravelerId string The traveler’s ID for the frequent traveler reward program.
HadDeposit boolean Whether the booking had a deposit. Format: true/false
IsUpgradeAllowed boolean Whether the booking can be upgraded. Format: true/false
ModificationCode string The code for the modification to the booking.
PartnerMembershipId string The membership ID of the partner associated with the booking.
PassiveType string The type of the booking.
RateAccess string The rate access for the booking.
RateType string The rate type for the booking.
UpgradedDateTime dateTime The date and time the booking was upgraded. Format: YYYY-MM-DDThh:mm:ss
VendorFlags string Semi-colon-delimited list of flags for free hotel service flags. For example, free breakfast (FB), internet (FI), Parking (FP), etc. If they were all present they can be concatenated as - FB;FI;FP;
VendorName string The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary.

Dining Booking Elements

The Dining Booking parent element is the Dining Element in the Segments Array in Booking Elements. This parent element contains a Dining Booking child element for each booked meal.

Element Date Time TripLink Description
ConfirmationNumber string The confirmation number from the vendor.
CancellationNumber string The cancellation number from the vendor. This field should be set when you cancel a segment.
Charges Parent Element The charges for this booking. For more information, see the Charges Elements table later on this page.
DateCancelledUtc dateTime The date the booking was cancelled, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateCreatedUtc dateTime The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateModifiedUtc dateTime The date the booking was modified, in UTC. Format: YYYY-MM-DDThh:mm:ss
EndDateLocal dateTime The booking ending time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss
EndDateUtc dateTime The booking ending time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss
FrequentTravelerId string The loyalty program ID for the user.
IsUpgradeAllowed boolean Whether the booking can be upgraded. Format: true/false
Name string The name of the restaurant. Maximum length: 80
Notes string Additional information about the booking.
NumPersons unsignedByte The number of persons for the booking.
PhoneNumber string The restaurant phone number.
RestaurantId string The booking vendor’s restaurant ID. Maximum length: 50
StartAddress string The restaurant address. Maximum length: 80
StartAddress2 string The restaurant address. Maximum length: 80
StartCity string The restaurant address. Maximum length: 50
StartCountry string The restaurant address.
StartDateLocal dateTime The booking starting time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss
StartDateUtc dateTime The booking starting time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss
StartLatitude string The latitude of the restaurant.
StartLongitude string The longitude of the restaurant.
StartPostalCode string The restaurant address. Maximum length: 24
StartState string The restaurant address. Maximum length: 50
Status string The status of the segment.
TimeZone string The time zone of the booking. Format: One of the supported Olson or Windows Time Zones.
UpgradedDateTime dateTime The date and time the booking was upgraded. Format: YYYY-MM-DDThh:mm:ss
Vendor string The two letter GDS vendor code.
VendorName string The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary.

Ride Booking Elements

The Ride Booking parent element is the Ride Element in the Segments Array in Booking Elements. This parent element contains a Ride Booking child element for each booked ride.

Element Data Type TripLink Description
ConfirmationNumber string The confirmation number from the vendor.
EndCityCode string The ending IATA airport code of the booking.
StartCityCode string The starting IATA airport code of the booking.
Vendor string The two letter GDS vendor code. See the Ride Codes table for ride vendor codes. For an unknown vendor, use the code value $$.
CancellationNumber string The cancellation number from the vendor. This field should be set when you cancel a segment.
CancellationPolicy string The cancellation policy from the vendor.
Currency string The 3-letter ISO 4217 currency code for the booking.
DateCancelledUtc dateTime The date the booking was cancelled, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateCreatedUtc dateTime The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateModifiedUtc dateTime The date the booking was modified, in UTC. Format: YYYY-MM-DDThh:mm:ss
DropoffInstructions string Instructions regarding the booking.
Duration integer The duration of the booking.
EndAddress string The ending address of the booking.
EndAddress2 string The ending address of the booking.
EndCity string The ending address of the booking.
EndCountry string The ending address of the booking.
EndDateLocal dateTime The booking ending time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss
EndDateUtc dateTime The booking ending time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss
EndLatitude string The latitude for the ending location of the booking.
EndLocation string The ending location of the booking.
EndLocationCode string The ending location code of the booking.
EndLocationName string The ending location name of the booking.
EndLongitude string The longitude of the ending point of the booking.
EndPostalCode string The ending address of the booking.
EndState string The ending address of the booking.
IsPersonal boolean Whether the segment is for personal travel. Format: true/false.
IsUpgradeAllowed boolean Whether the booking can be upgraded. Format: true/false
MeetingInstructions string The instructions for the meeting location of the booking.
Miles integer The number of miles for the booking.
Name string The name on the booking.
Notes string Additional information about the booking.
NumberOfHours double The number of hours of the booking.
NumPersons unsignedByte The number of people included in the booking.
OperatedByVendor string The operated by vendor for the booking.
PassiveCityCode string The passive city code of the booking.
PhoneNumber string The ride vendor phone number.
PickupInstructions string Instructions regarding the booking.
Rate string The rate for the booking.
RateDescription string The rate description for the booking.
RateNotes string The rate notes for the booking.
RateType string The rate type for the booking.
ReservationId string The booking vendor’s reservation ID.
SpecialInstructions string The special instructions for the ride. Max Length: 256
StartAddress string The starting address of the booking.
StartAddress2 string The starting address of the booking.
StartCity string The starting address of the booking.
StartCountry string The starting address of the booking.
StartDateLocal dateTime The booking starting time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss
StartDateUtc dateTime The booking starting time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss
StartLatitude string The latitude of the booking start location.
StartLocation string The starting location of the booking.
StartLocationCode string The code of the starting location of the booking.
StartLocationName string The name of the starting location of the booking.
StartLongitude string The longitude of the booking start location.
StartPostalCode string The starting address of the booking.
StartState string The starting address of the booking.
Status string The status of the segment.
TimeZone string The time zone of the booking. Format: One of the supported Olson or Windows Time Zones.
UpgradedDateTime dateTime The date and time the booking was upgraded. Format: YYYY-MM-DDThh:mm:ss
VendorName string The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary.
Charges Parent Element The charges for this booking. For more information, see the Charges Elements table.

Rail Booking Elements

The Rail Booking parent element is the Rail Element in the Segments Array in Booking Elements. This parent element contains a Rail Booking child element for each booked rail segment.

Element Data Type TripLink Description
ConfirmationNumber string The confirmation number from the vendor.
StartDateLocal dateTime Y The starting date of travel for this segment, in the local time of to the starting point. Format: YYYY-MM-DDThh:mm:ss
Amenities string The booked amenities.
Cabin string The cabin identifier.
CancellationNumber string The cancellation number from the vendor. This field should be set when you cancel a segment.
CarbonEmissionLbs decimal The pounds of carbon emission for this booking.
CarbonModel integer The model used to calculate the carbon emissions.
ClassOfService string The class of the booking.
CreditCardType String The type of credit card (for example, Visa/Mastercard/etc.).
CreditCardLastFour String The last four digits of credit card number.
Currency string The 3-letter ISO 4217 currency code for the booking.
DateCancelledUtc dateTime The date the booking was cancelled, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateCreatedUtc dateTime The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateModifiedUtc dateTime The date the booking was modified, in UTC. Format: YYYY-MM-DDThh:mm:ss
DiscountCode string The discount code for the booking.
Duration integer The duration of the trip booked.
EndCity string The end city for the rail trip.
EndCityCode string The IATA airport code for the end city of the trip.
EndCountry string The country code for the booking.
EndDateLocal dateTime Y The booking ending time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss
EndDateUtc dateTime Y The booking ending time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss
EndLatitude string The latitude of the ending point of the booking.
EndLongitude integer The longitude of the ending point of the booking.
EndPlatform string The ending platform location of the booking.
EndRailStation string Y The code for the ending station of the booking.
EndRailStationName string Y The name of the ending station of the booking.
ETicket integer The e-ticket number.
FareType string The type of fare on the rail booking.
FrequentTravelerId string The traveler’s ID for the frequent traveler reward program.
IsUpgradeAllowed boolean Whether the booking can be upgraded. Format: true/false
LegId string The trip leg ID.
Meals string The booked meals.
Miles integer The number of miles booked.
Notes string Additional information about the booking.
NumPersons unsignedByte The number of persons booked for the trip.
NumStops unsignedByte The number of stops in the booking.
OperatedByTrainNumber string The train identifier of the operating vendor of the booked trip.
OperatedByVendor string The operating vendor of the booked trip.
RateCode string The vendor's code for the rate of the booking.
RouteRestrictCode string The code to restrict the route of the booking.
SpecialInstructions string The instructions for the booking. Max Length: 256
StartCity string The starting city of the booking.
StartCityCode string Y The IATA airport code for the starting city of the booking.
StartCountry string The starting country of the booking.
StartDateUtc dateTime Y The starting date of travel for this segment, in UTC. Format: YYYY-MM-DDThh:mm:ss
StartLatitude string The latitude of the starting location of the booking.
StartLongitude string The longitude of the starting location of the booking.
StartPlatform string The starting platform location of the booking.
StartRailStation string Y The code of the starting station of the booking.
StartRailStationName string Y The name of the starting station of the booking.
Status string The booking status.
TimeZone string The time zone of the booking. Format: One of the supported Olson or Windows Time Zones.
TotalRate decimal The total rate amount of the booking.
TrainNumber string The number for the booked train.
TrainTypeCode string The code for the type of train used in the booking.
TrainTypeName string The name of the type of train used in the booking.
TransportMode sring The transport mode of the booking.
UpgradedDateTime dateTime The date and time the booking was upgraded. Format: YYYY-MM-DDThh:mm:ss
Vendor string The two letter GDS vendor code.
VendorName string The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary.
WagonNumber string The wagon number of the train car.
Charges Parent Element The charges for this booking. For more information, see the Charges Elements table.
Seats Parent Element The booked seats. This parent element contains a RailSeat element for each included seat. For more information, see the RailSeat Elements table later on this page.
RailSeat Elements
Element Data Type TripLink Description
Amenities string The amenities for the seat.
BerthPosition string The berth location of the seat.
Deck string Which deck the seat is on.
FacingForward string Whether the seat is facing forward.
FareSpaceComfort string The space around the seat.
PassengerRph integer Which passenger the seat is assigned to.
SeatNumber string The number of the seat.
SeatPosition string The location of the seat.
SpaceType string The type of space around the seat.
Status string The status of the seat booking.
WagonNumber string The number of the wagon the seat is on.
WagonType string The type of wagon the seat is on.

Parking Booking Elements

The Parking Booking parent element is the Parking Element in the Segments Array in Booking Elements. This parent element contains a Parking Booking child element for each booked parking.

Element Data Type TripLink Description
ConfirmationNumber string The confirmation number from the vendor.
StartDateLocal dateTime The starting date of travel for this segment, in the local time of to the starting point. Format: YYYY-MM-DDThh:mm:ss
CancellationNumber string The cancellation number from the vendor. This field should be set when you cancel a segment.
ClassOfService string The class of the booking.
Currency string The 3-letter ISO 4217 currency code for the booking.
DateCancelledUtc dateTime The date the booking was cancelled, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateCreatedUtc dateTime The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateModifiedUtc dateTime The date the booking was modified, in UTC. Format: YYYY-MM-DDThh:mm:ss
EndDateLocal dateTime The booking ending time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss
EndDateUtc dateTime The booking ending time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss
FrequentTravelerId string The traveler’s ID for the frequent traveler reward program.
IsUpgradeAllowed boolean Whether the booking can be upgraded. Format: true/false
Notes string Additional information about the booking.
OperatedByVendor string The operating vendor of the booking.
ParkingLocationId string The location of the parking booking.
PhoneNumber string The parking phone number.
Pin string The PIN number for the booking.
RateCode string The vendor's code for the rate of the booking.
StartAddress string The starting address of the booking.
StartAddress2 string The starting address of the booking.
StartCity string The starting address of the booking.
StartCityCode string The IATA airport code for the starting city of the booking.
StartCountry string The starting address of the booking.
StartDateUtc dateTime The starting date of travel for this segment, in UTC. Format: YYYY-MM-DDThh:mm:ss
StartLocation string The parking location.
StartPostalCode string The starting address of the booking. Maximum length: 24
StartState string The starting address of the booking. Maximum length: 50
Status string The booking status.
TimeZone string The time zone of the booking. Format: One of the supported Olson or Windows Time Zones.
TotalRate string The total rate amount of the booking.
UpgradedDateTime dateTime The date and time the booking was upgraded. Format: YYYY-MM-DDThh:mm:ss
Vendor string The two letter GDS vendor code.
VendorName string The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary.
Charges Parent Element The charges for this booking. For more information, see the Charges Elements table later on this page.

Travel Booking Elements

The Travel Booking parent element is the Travel Element in the Segments Array in Booking Elements. This parent element contains a Travel Booking child element for each booked travel request.

NOTE: This booking type is used by the Concur Travel Request product to store the main destination for the trip without specifying a transport type.

Element Data Type TripLink Description
CancellationNumber string The cancellation number from the vendor. This field should be set when you cancel a segment.
ConfirmationNumber sring The confirmation number from the vendor.
CreditCardType String The type of credit card (for example, Visa/Mastercard/etc.).
CreditCardLastFour String The last four digits of credit card number.
Currency string The 3-letter ISO 4217 currency code for the booking.
DailyRate decimal Average per day rate for the booking. If the rate varies over the duration, it can be specified using the charges model.
DateCancelledUtc dateTime The date the booking was cancelled, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateCreatedUtc dateTime The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateModifiedUtc dateTime The date the booking was modified, in UTC. Format: YYYY-MM-DDThh:mm:ss
EndAddress string The ending address of the booking.
EndAddress2 sring The ending address of the booking.
EndCity string The ending address of the booking.
EndCityCode string The IATA airport code for the ending city of the booking.
EndCountry string The ending address of the booking.
EndDateLocal dateTime The booking ending time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss
EndDateUtc dateTime The booking ending time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss
EndLatitude string The latitude for the ending location of the booking.
EndLocation sring The ending location of the booking.
EndLongitude string The longitude of the ending point of the booking.
EndPostalCode string The ending address of the booking.
EndState sring The ending address of the booking.
TransportMode string The transport mode of the booking.
Notes string Additional information about the booking.
NumPersons unsignedByte The number of persons booked for the trip.
PhoneNumber string The booking phone number.
SpecialInstructions sring The instructions for the booking. Max Length: 256
StartAddress string The starting address of the booking.
StartAddress2 string The starting address of the booking.
StartCity sring The starting address of the booking.
StartCityCode string The IATA airport code for the starting city of the booking.
StartCountry string The starting address of the booking.
StartDateLocal dateTime The starting date of travel for this segment, in the local time of to the starting point. Format: YYYY-MM-DDThh:mm:ss
StartDateUtc dateTime The starting date of travel for this segment, in UTC. Format: YYYY-MM-DDThh:mm:ss
StartLatitude string The latitude of the booking.
StartLongitude sring The longitude of the booking.
StartPostalCode string The starting address of the booking. Maximum length: 24
StartState string The starting address of the booking. Maximum length: 50
Status string The booking status.
TimeZone sring The time zone of the booking. Format: One of the supported Olson or Windows Time Zones.
TotalRate decimal The total rate amount of the booking.
Vendor string The two letter GDS vendor code.
VendorName string The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary.
Charges Parent Element The charges for this booking. For more information, see the Charges Elements table.
Charges Elements
Element Data Type TripLink Description
Percent Parent Element The percent of fixed charges. For more information about the child elements of this parent element, see the Percent Elements table.
Fixed Parent Element The fixed charges. For more information about the child elements of this parent element, see the Fixed Elements table.
Rate Parent Element The rate for the booking. For more information about the child elements of this parent element, see the Rate Elements table.
RateWithAllowance Parent Element The rate for the booking, including any travel allowances. For more information about the child elements of this parent element, see the RateWithAllowance Elements table.
Rate Elements
Element Data Type Description
Amount decimal The total amount for the rate for the booking.
Currency string The 3-letter ISO 4217 currency code for the total amount.
Description string The description for the rate.
IsPaid boolean Whether the rate has been paid. Format: true/false.
IsPrimary boolean Whether the rate is primary. Format: true/false.
NumUnits decimal The number of units expected for the charge. For instance, 3 days
PerUnit string The unit of measure for the charge. Values represent rates like per DAY, WEEK, or MONTH
SemanticsCode string Indicates the charge category for the line item. Refer to the Semantics Codes table for more information.
SemanticsVendorType string The vendor type: H=Hotel, C=Car, A=Air, G=Ground, R=Rail
StartDateLocal dateTime The start date of the booking, in the user's local time. Format: YYYY-MM-DDThh:mm:ss
Vendor string The vendor for the booking charge.
VendorChargeCode string The vendor's code for the charge.
RateWithAllowance Elements
Element Data Type TripLink Description
AllowanceAmount decimal The cost of overage fees when the allowance is exceeded. For example, if the allowance is 5000 miles, the cost could be $0.02 per mile. The overage must be in the same currency as the basic rate.
AllowanceIsUnlimited boolean Whether the allowance is unlimited. Format: true/false.
AllowanceNumUnits decimal The number of units for the allowance associated with the charge. For example, 5000 miles.
AllowanceUnit string The unit of measure for the allowance associated with the charge. For example, a car weekly rate might allow 5000 miles included in the rate.
Amount decimal The total amount for the rate for the booking.
Currency string The 3-letter ISO 4217 currency code for the total amount.
Description string The description for the rate.
IsPaid boolean Whether the rate has been paid. Format: true/false.
IsPrimary boolean Indicates whether the charge is the Primary or Main rate. For example, if one of the rates is the actual rate and the rest are penalties, the actual rate should be set as IsPrimary. Only one charge in a set should be primary. Format: true/false.
NumUnits decimal The number of units expected for the charge. For instance, 3 days.
PerUnit string The unit of measure for the charge. Values represent rates like per DAY, WEEK, or MONTH
SemanticsCode string Indicates the charge category for the line item. Refer to the Semantics Codes table for more information.
SemanticsVendorType string The vendor type: H=Hotel, C=Car, A=Air, G=Ground, R=Rail
StartDateLocal dateTime The start date of the booking, in the user's local time. Format: YYYY-MM-DDThh:mm:ss
Vendor string The vendor for the booking charge.
VendorChargeCode string The vendor's code for the charge.

Car Vendor Codes

Return to Reference topics

The following car vendor codes are used in the Car Booking Elements.

Vendor Code Vendor Name
FA Able
AC Ace
AD Advantage
AL Alamo
LV Allstate
AF Americar
ZU AutoEurope
ZI Avis
CH Charlie
CP Compass
CO Continental
DS Discount
ZR Dollar
ET Enterprise
ED Eurodollar
EP Europcar
FH Falles Hire Cars
FD Ford Dealer
HO Holiday Car
IM Imperial
IA Independent Auto
TS Intl Travel
KG Kemwel Holiday
KN Kenning
LL Localiza
ZW Montgomery Ward
NE Nationwide
ZA Payless
PI Pinellas
BL Red And Blue
RR Rent Rite
RS Resort
ZS Sears
SX Sixt
ZT Thrifty
CC Country Car
TR Triangle
CT TT/Key Services
SV U-Save
CY Carey International
CV Capps Vans
AB All American
EE Exoticar Express
LX Limo Service
MW Midway
NF New Frontier
SL SL I.T.S.
US US Rent a Car
VR Specialty Van
WC West Coast
ZH Simply Wheelz
NU Nu Car Rentals
EY Economy Rent a Car
$$ Unknown Car Vendor
ZM Zoom Rent a Car
ZD Budget
ZE Hertz
ZL National
AU Austrian
DR DER Travel Svcs
EN Vip Car Rental
ML Merlin
EZ Ez Rent A Car
FX Fox
LM L & M Car Rental
SW Southwest
NW New Frontier

Hotel Vendor Codes

Return to Reference topics

Vendor Code Vendor Name
RT AccorHotels
AM Adams Mark
AZ The Ascott Limited
AS All Suites
AR AC Hoteles
AJ AmeriSuites
AN Ana Hotels
AX Anasazi Service
AQ ATA Hotels
AO Atlantis Hotel
AH Aston Hotels
AP Andre Balazs
AC Atel France
BB Bartell Hotels
BW Best Western
BM Biltmore
BU Baymont Inns
CJ Caesar Park
QC Camberly
CA Confortel
CO Camino Real Htls
CV COMO Hotels and Resorts
CE Chalet Susse
CR Clarion
CH CIH Hotels
WX Coast Hotels
CS Classical Hotels
CI Comfort Inns
CD Concord Hotels
WA Waldorf Astoria
BC Boutiquw
CX Country Inn
CL Corus Hotels
DC Dorchester Htls
DE Delta Hotels
DS Design Hotels
FT Grande Hotels
DV De Vere
DA Doral Hotels
DO Dorintresorts
DT Doubletree
DY Doyle Hotels
DR Drury Inns
EE Marriott Exec Ap
EO Econo Lodge
ER Electronic Rep
EU Exclusive Htls
RM Hetras
XH Extra Holidays
FA Fairmont Hotels
FQ Fauriel
FM Fiesta American
FE Forte Hotels
FS Four Seasons
FZ Friendship Inns
FC Rocco Forte
GX Global Conextion
HN Linkhotel
GR Six Senses Hotel
GT Golden Tulip
AG Gouverner Hotel
GN Gramercy Park Hotel
GH Grand Heritage
GD Grand Tradition
HB Hbs Hotel Booki
HX Hampton Inns
HR Harrah's
HV Harvey Hotels
HP Hyatt Place
BH Hawthorn Suites
HL Hilton Intl
BE Homestead Studio
HG Homewood Suites
HO Hotelrez
AI Armani Hotels
HW Hotel World
HQ Hotelink Intl
HA HOTUSA Hotels
MR Morgans Hotel Group
IL Innlink Res Svc
IP InnPoints
IG Insignia Resorts
IC InterContinental
IE InterEurope Htls
IT Intl Trvl Resort
TS Intl Trvl Svcs
IR Innpoints
JA Jarvinen Hotels
JY Jolly Hotels
KA Karos Hotels
KI Kempinski
KY Keytel
KC Kimpton Hotels
KN Kintetsu Intl
NV Las Vegas Travel
LW Leading Hotels
LM Vantis Hotel GRP
LA Little America
LZ Loews Hotels
LR LRI
LU Luxor Hotel
MY Personality Hotels
MZ Mainstay Suites
MO Mandarin Orientl
MH Marco Polo Htls
MM Maritim Hotels
ET Marriott Cnf Ctr
MG Magnolia Hotels
MF Micros Fidelio
MT Microtel Hotels
MU Millennium Htls
MP Mantra Group
MN Montage Hotels A
MI Malmaison Hotels
MK Movenpick Htls
ND National Hotels
NO New Otani
NK Nikko Hotels
NH Nippon Travel
OB Oberoi Group
OC Okura Hotels
OM Omni Hotels
OH Oslo Hotel
OR Outrigger
PS Sandman Hotels
PF Pan Pacific
PL Parkroyal Hotels
PQ Purple Hotels
PH Preferred Hotels
PW Prima Hotels
PN Peninsula Hotels
PR Protea Hotels
QI Quality Inns
QL Queens Hotels
QM Queens Moat Htls
QH QHotels
RD Radisson
NR Ramada Intl
ON Reconline
RL Red Lion Inns
RF Red Roof Inns
RQ Regal Hotels
KR Regal Hotels UK
RE Regent Intl
RH Reservations Hub
BR Renaissance Intl
RC Residence Inns
RR Righa Royal
RZ Ritz-Carlton
RW Rosewood
RI Rodeway Inns
RO Rotana Hotels and Resorts
RB Resort Bookings
RG Rydges Group
SH Scandic Hotels
IQ Myfidelio
SC Sceptre Hotels
SQ Select Hotels
SG Shangri-La
BP Shilo Inns
US Sierra Hotels
SJ Jameson Inns
SZ Sleep Inns
SB Sofitel
LX Small Luxury
SM InnLink Res Svc
SN Sonesta Hotels
ST Sorat Hotels
SP Special Prop-IHG
XV SpringHill Suites
SR Steigenberger
SK Stakis Hotels
YS Stamford Hotels
LV Las Vegas Test
YZ Staybridge Ste
WR Sterling Intl
SS Studio 6
XL Summit Hotels
SX Supranational
UK Swallow Hotels
SL Swissotel
TI Thistle Hotels
TM Tianma
TP Top Intnl Htls
TH Trident Hotels
TO TownePlace Suites
TA Reservhotel
TX Treff Hotels
TR Cendant Trip Rewards
VP VIP Intl
VA OneTech Solution
VI Vienna International
WH W Hotels
DW Walt Disney Htl
WK Warwick Hotels
WL Wellesley Inns
WM Westmark Hotel
EJ Williams
WC WestCoast Hotels
WW World Hotels
WY Wyndham Hotels
SW Starwood (All)
AL Aloft Hotels
BY Banyan Tree
EL Elements
GA Global Alliance
IW Hotels & Preference
QX Luxury Lifestyle
RP Rendezvous Hospitality Group
RU Hard Rock
TY Tradyso Global Distribution
ZX Marriott Affliat
TB GTA TravelBound
DX Dolce Hotels
JI Jurys Inns
LD Leonardo
LJ Lalit
NZ Ascend
IN Indigo Hotels
LC Luxury Collection
LI LeisureLink Inc
OT Othon Hotels
PX Performance Conn
PY Peabody Hotels
SE Sercotel
WF West Coast Famil
ZC Ritz Club
XO Luxury Resorts
AT Address Hotels
CQ Club Quarters
ML Melrose Hotels
DH Distinguished Hotels
PI Premier Inn
ZZ Independent
JT Jumeirah
EZ Cambria Suites
UB Suburban Extended Stay
FB Fontainebleau
GV Graves Hotels
IM Independent Htls
JL Jumeriah
LP Lexington
OP Omni Partners
PV Preferred Group
RJ Resort Condos
RK Rezlink Intl
UV Univisit
VK Vacationclick
VR Vacation Rentals
XN Global Res
XX New Synxis
XZ Hotelzon
OI Amadeus LinkHotel
GF Grange Hotels
EP Epoque Hotels
LO Langham Hotels
PM Barcelo Hotels
QV ResortQuest Intl
XW WebRes
YH Booking Services
YP Altiuspar Soluti
DD Derag Hotels
XR St Regis
6C Intercontinental Hotels Group
AB Abba Hotels
AE AmeriHost Inn
AV Allegience Svcs
AW Astra Worldwide
BA Boscolo Hotels
BG Bulgari Hotels
BN Barcelo Hotels
BV Best Value Inns
CG City Lodge Group
CN Conrad
CP Crowne Plaza
CU Charming Hotels
CW Carlson Brands (All)
CZ Comfort Suites
DI Days Inn
DM Domina Hotels
DU Destinations Unl
EC Choice Brands
EH Hilton (All)
EK Sercotel
EM Marriott (All)
GI Hilton Garden Inn
GM Meritus
GW Great Hotels
HE Historic Hotels
HF HomeGate Studios
HU Hyatt Vacation
ID Resnet
IF ACC-NIFOS
IS Ian Schrager
IU Intourist Travel
JC Cendant Brands (All)
JU Jumer
KL ClubHouse Inns
LT Travelodge AU
MS Magnuson Hotels
MV MGM Mirage
NN Louvre Hotels
NY Denihan Hospitality Group
OE Orient Express
OK Alesia
OS Sweden Hotels
PK Park Plaza Intl
PT Prime Hotels
RA Ramada Hotels
RN Expotel
RX Ringhotels
SO Sonesta
SV Sarova Hotels
SY Starhotels
TL Travelodge
TV ReservHotel
VC Marriott Vacation Club
WD Chase Suite Hotels
WG Wingate Inn
XS Summerfield Suites
II Indecorp
GZ Genares Worldwide
GE Gaylord Hotels
FV Flairview
EW Exclusive World
GQ Genre Hotels
FX First Hotel
WT Tryp by Wyndham
UN Carino Hotels
GP Husa Hotels
IV InnVite
LG Lindner Hotels
JJ Jin Jiang Hotels
CK Black Pepper Hotels
QO Swiss Quality Hotels
AK Autograph
EB Edition
EQ Eaton
FD Etours
HM Missoni
JG JG Black Book
OO One And Only
UA Premier Connect
PU Pullman
QG Quest
TW Trump Hotel Collection
TF Thon Hotels
IA Corinthia Hotels
NU Northwood Hospitality
HC hotel.de
$$ Unknown Hotel Vendor
QU Aqua Hotels and Resorts
FG FastBooking
BL Balladins Hotels
ZW CWT Private Hotels
DN Destination
XE Excalibur
CY Courtyard
ES Embassy Suites
FN Fairfield Inns
HH Hilton
HI Holiday Inn
HJ Howard Johnson
HY Hyatt
MC Marriott
SI Sheraton
WI Westin
CB Classic British
HT Home2 Suites
JH Jumer Hotels
LQ La Quinta Inns
QR Quality Htl Res
SU Southern Sun
UI Utell
PD Park Inn
SF Sutton Place Htl
YO Candlewood Stes
KG Knights Inn
VG Villager
OZ Super 8
VY Maybourne Hotels
JD Doyle Collection
EA Extended Stay
VE Vantis Hotels
YX Synxis Res Svcs
BK Interstate Hotels and Resorts
MD Le Meridien
LE Luxe Worldwide
KH K Hotels
FW Flag Hotels
UZ Unirez
GO Guesthouse International
TG Travelodge UK
WO WorldRes
JV Joie De Vivre
PJ Prince Resorts
BI Best Inns
MB Mandalay Bay
YR Raffles Intl
FH Fiesta Americana
NS NH Hotels
NC Noble House
OG Olympus Hospitality
RS Rockresorts Intl
GB MacDonald Group
WB Relais/Chateaux
GG Grand Hosp.
AA AmericInns
MX Motel 6
DL Doral Resorts
CC Clarion
BT BT Advantage
SA Sabre Exclusives
RV Red Roof Inns
TJ Taj Hotels
BX Columbus Res Svc
BZ Cmnet Brazil
CM Camino Real
DJ Hotel Port
EI Executive Hotels
HK Hot Key Intl.
IH CIH Hotels
KO KSL Resorts
ME Sol Melia
NW Newtrade
PG Phillips Hotel
UE Universal Resort
WS World Res
WV TravelCLICK

Ride Vendor Codes

Return to Reference topics

Vendor Code Vendor Name
$R RideCharge
AL AddisonLee
DG DeemGroundLimo
GC GroundScope
GS GroundSpan
LC Limoscom
SQ SummitQwest
SW SummitQwest
TD Tandem
TV Transvip

Semantics Codes

Return to Reference topics

The semantics codes are used in the Charges child elements in Bookings.

Vendor Type Semantics Code Description
Hotel OTHER Other miscellaneous charges
Hotel BUSINESS Business center charges
Hotel CONFERENCE Conference charges
Hotel COUNTYTAX County tax
Hotel VAT VAT tax
Hotel GST GST tax
Hotel FEDERALTAX Federal tax
Hotel FOOD Food/beverage charges: hotel restaurant, room service
Hotel ALCOHOL Alcohol charges: beer, wine, and liquor at restaurant
Hotel FOODTAX Food/beverage taxes
Hotel GIFT Gift shop charges
Hotel GENERALTAX General taxes
Hotel HEALTH Health club, pool, court, golf, etc.
Hotel LAUNDRY Laundry
Hotel MINIBAR In room mini-bar
Hotel CITYTAX City tax
Hotel MOVIE Movie, in room entertainment
Hotel GAME Game, in room entertainment
Hotel PARKING Parking/Valet
Hotel PST PST tax
Hotel STATETAX State tax
Hotel PAYMENT Payment
Hotel DISCOUNT Discount
Hotel ROOMRATE Room rate
Hotel ROOMTAX Room tax
Hotel GRATUITY Gratutities, tips
Hotel PHONE Telephone charges
Hotel INTERNET Internet charges
Hotel NOSHOW No show fee
Hotel NEGOTIATEDRATE Negotiated room rate
Car DAYS DAYS
Car WEEKS WEEKS
Car MONTHS MONTHS
Car EXTRAHOURS EXTRA HOURS
Car EXTRADAYS EXTRA DAYS
Car EXTRAWEEKS EXTRA WEEKS
Car MILEAGEFEE MILEAGE FEE
Car UPGRADEFEE UPGRADE FEE
Car ADJUSTMENT ADJUSTMENT
Car DISCOUNT DISCOUNT
Car COLLECTION COLLECTION
Car DELIVERY DELIVERY
Car INTERCITY INTERCITY
Car ADDLDRIVER ADDITIONAL DRIVER
Car SERVICECHARGE SERVICE CHARGE
Car LDWCDW LDW/CDW
Car ALIAMOUNT ALI AMOUNT
Car PAIPECAMOUNT PAI/PEC AMOUNT
Car THEFTPROTECT THEFT PROTECTION
Car FUELSERVICE FUEL SERVICE
Car AIRPORTFEE AIRPORT FEE
Car AGEDIFFER AGE DIFFERENTIAL
Car CHILDSEAT CHILD SEAT
Car SKIRACK SKI RACK
Car ADDLSERVICE ADDITIONAL SERVICE
Car OTHERCHARGES OTHER CHARGES
Car TRANSACTIONFEE TRANSACTION FEE
Car SATELLITERADIO SATELLITE RADIO
Car NEVERLOST NEVERLOST
Car ACSURCHARGE A/C SURCHARGE
Car RESERVATIONFEE RESERVATION FEE
Car TAXDIFFER TAX DIFFERENTIAL
Car VOUCHERADJUST VOUCHER ADJUSTMENT
Car VATAMOUNT VAT AMOUNT
Car GSTAMOUNT GST AMOUNT
Car VEHICLELICENSE VEHICLE LICENSE FEE
Car CUSTFACILITY CUSTOMER FACILITY
Car VEHLEASETAX MOTOR VEHICLE LEASE TAX
Car ROADTAX ROAD TAX
Car OTHER OTHER
Car ACRECOVERYFEE AIR CONDITION RECOVERY FEE
Car CONCESSIONFEE CONCESSION PASS THRU FEE
Car CUSTRELATIONS CUSTOMER RELATIONS EXPENSE
Car TFFCORPVRT TFFC OR PVRT
Car IMPOUNDSTORAGE IMPOUND/STORAGE
Car LISAMOUNT LIS AMOUNT
Car SUPLIABILITY SUPPLEMENTAL LIABILITY PROTECTION
Car DROPOFFFEE DROPOFF FEE
Car WEEKEND WEEKEND DAILY RATE
Air OTHER Miscellaneous charge
Air SEGFEE Segment fee
Air SEGFEE_AS_FEE Segment fees as fee
Air SEGFEE_AS_FARE Segment fees as base fare
Air SEGFEE_AS_TAX Segment fee as tax
Air WIRELESS_FEE Wireless Fee
Rail OTHER Miscellaneous charge
Rail TICKET Price of ticket
Rail SEAT Price of seat

Time Zones

Return to Reference topics

SAP Concur converts local date/time to UTC. In order to do that we need to be able to determine where the local time is.

Olson Time Zones

Africa/Cairo Africa/Casablanca Africa/Harare Africa/Luanda
Africa/Nairobi Africa/Windhoek America/Anchorage America/Argentina/Buenos_Aires
America/Asuncion America/Bahia America/Bogota America/Buenos_Aires
America/Caracas America/Chicago America/Chihuahua America/Denver
America/Godthab America/Guyana America/Halifax America/Indianapolis
America/Los_Angeles America/Manaus America/Mexico_City America/Montevideo
America/New_York America/Phoenix America/Regina America/Santiago
America/Sao_Paulo America/St_Johns America/Swift_Current America/Tijuana
Asia/Almaty Asia/Amman Asia/Baghdad Asia/Baku
Asia/Bangkok Asia/Beirut Asia/Calcutta Asia/Colombo
Asia/Damascus Asia/Dhaka Asia/Irkutsk Asia/Jerusalem
Asia/Kabul Asia/Kamchatka Asia/Karachi Asia/Karachi
Asia/Katmandu Asia/Krasnoyarsk Asia/Magadan Asia/Muscat
Asia/Novosibirsk Asia/Rangoon Asia/Riyadh Asia/Seoul
Asia/Shanghai Asia/Singapore Asia/Taipei Asia/Tbilisi
Asia/Tehran Asia/Tokyo Asia/Ulaanbaatar Asia/Vladivostok
Asia/Yakutsk Asia/Yekaterinburg Asia/Yerevan Atlantic/Azores
Atlantic/Cape_Verde Atlantic/South_Georgia Australia/Adelaide Australia/Brisbane
Australia/Darwin Australia/Hobart Australia/Perth Australia/Sydney
Etc/GMT+12 Etc/GMT-11 Etc/GMT-2 Europe/Athens
Europe/Berlin Europe/Helsinki Europe/Istanbul Europe/Kaliningrad
Europe/London Europe/Minsk Europe/Moscow Europe/Paris
Europe/Prague Europe/Sarajevo GMT GMT-1200
Indian/Mauritius Pacific/Apia Pacific/Auckland Pacific/Fiji
Pacific/Guadalcanal Pacific/Guam Pacific/Honolulu Pacific/Tongatapu
UTC

Windows Time Zones

Return to Reference topics

Africa/Cairo Africa/Casablanca Africa/Harare Africa/Luanda
Africa/Nairobi Africa/Windhoek America/Anchorage America/Argentina/Buenos_Aires
America/Asuncion America/Bahia America/Bogota America/Buenos_Aires
America/Caracas America/Chicago America/Chihuahua America/Denver
America/Godthab America/Guyana America/Halifax America/Indianapolis
America/Los_Angeles America/Manaus America/Mexico_City America/Montevideo
America/New_York America/Phoenix America/Regina America/Santiago
America/Sao_Paulo America/St_Johns America/Swift_Current America/Tijuana
Asia/Almaty Asia/Amman Asia/Baghdad Asia/Baku
Asia/Bangkok Asia/Beirut Asia/Calcutta Asia/Colombo
Asia/Damascus Asia/Dhaka Asia/Irkutsk Asia/Jerusalem
Asia/Kabul Asia/Kamchatka Asia/Karachi Asia/Karachi
Asia/Katmandu Asia/Krasnoyarsk Asia/Magadan Asia/Muscat
Asia/Novosibirsk Asia/Rangoon Asia/Riyadh Asia/Seoul
Asia/Shanghai Asia/Singapore Asia/Taipei Asia/Tbilisi
Asia/Tehran Asia/Tokyo Asia/Ulaanbaatar Asia/Vladivostok
Asia/Yakutsk Asia/Yekaterinburg Asia/Yerevan Atlantic/Azores
Atlantic/Cape_Verde Atlantic/South_Georgia Australia/Adelaide Australia/Brisbane
Australia/Darwin Australia/Hobart Australia/Perth Australia/Sydney
Etc/GMT+12 Etc/GMT-11 Etc/GMT-2 Europe/Athens
Europe/Berlin Europe/Helsinki Europe/Istanbul Europe/Kaliningrad
Europe/London Europe/Minsk Europe/Moscow Europe/Paris
Europe/Prague Europe/Sarajevo GMT GMT-1200
Indian/Mauritius Pacific/Apia Pacific/Auckland Pacific/Fiji
Pacific/Guadalcanal Pacific/Guam Pacific/Honolulu Pacific/Tongatapu
UTC

Itinerary v4

Important: This API is currently in pre-release status and is only available to approved early access participants. The API is under development and might change before being generally released. To become an early access participant, contact your SAP Concur Representative.

Overview

The Itinerary API provides clients and authorized partners access to travel itinerary data.

Limitations: This API is only available to clients and partners who have been granted access by SAP Concur. Access to this documentation does not provide access to the API. This API is only available in US and EMEA data centers.

Prior Versions

Process Flow

Sequence Diagram

Products and Editions

Scope Usage

Name Description Endpoint
travel.itinerary.read Allows user to read travel itinerary data. GET

Dependencies

None.

Access Token Usage

This API supports only company level access tokens.

Retrieve a Trip Record

Retrieves the record of a trip.

Scopes

travel.itinerary.read - Refer to Scope Usage for full details.

Request

URI

Template
GET https://{region}.api.concursolutions.com/travel/v4/trips/{id}
Parameters
Name Type Format Description
region string - Required: Region of the trip. Supported values: us, eu
id string - Required The trip ID.

Headers

Response

Error Codes

Payload

Example

Request

GET https://us.api.concursolutions.com/travel/v4/trips/51519e89-2c1d-47ec-bd93-7c4ace9c57e6
Accept: application/json
Authorization: Bearer <JWT Token>

Response

HTTP/1.1 200 OK
Content-Type: application/json
{
    "BookedVia": "Agent",
    "Bookings": [
        {
            "AgencyName": "Outtask Travel Apollo",
            "AgencyPCC": "C4I",
            "AirfareQuotes": [
                {
                    "BaseFare": 1264,
                    "BaseFareCurrency": "EUR",
                    "DateCreatedUtc": "2020-11-04T20:54:19.000+00:00",
                    "DateModifiedUtc": "2020-11-04T20:54:19.000+00:00",
                    "IssueByDate": "2020-09-25T15:54:18.000-00:00",
                    "TotalFare": 1341.2,
                    "TotalFareCurrency": "EUR"
                }
            ],
            "AirlineTickets": {
                "AirlineAdjustment": [
                    {
                        "AddCollectAmount": 0,
                        "AdjustmentDateTime": "2020-11-02T00:00:00.000-00:00",
                        "AdjustmentType": "C",
                        "AirlineCharges": {
                            "Fixed": [
                                {
                                    "Amount": -23,
                                    "Currency": "EUR",
                                    "Description": "Ice cream with meal",
                                    "IsPaid": true,
                                    "IsPrimary": false
                                }
                            ]
                        },
                        "DateCreatedUtc": "2020-11-04T20:54:19.000+00:00",
                        "DateModifiedUtc": "2020-11-04T20:54:19.000+00:00",
                        "PassengerName": "EschIII/BenDwayne",
                        "PlatingCarrierNumericCode": "638",
                        "PlatingControlNumber": "0522482769",
                        "RecordLocator": "A56053",
                        "Taxes": [
                            {
                                "TaxAmount": 5,
                                "TaxAuthority": "USA",
                                "TaxName": "Silly Air Adjustment Tax",
                                "TaxRate": 0.58,
                                "TaxType": "US"
                            },
                            {
                                "TaxAmount": -5,
                                "TaxAuthority": "USA",
                                "TaxName": "Silly Air Adjustment Tax",
                                "TaxRate": 0.58,
                                "TaxType": "AY"
                            },
                            {
                                "TaxAmount": -9,
                                "TaxAuthority": "USA",
                                "TaxName": "Silly Air Adjustment Tax",
                                "TaxRate": 0.58,
                                "TaxType": "XF"
                            }
                        ],
                        "TotalAdjustment": -100,
                        "TotalAdjustmentCurrency": "USD"
                    }
                ],
                "AirlineTicket": [
                    {
                        "AccountingLine": {
                            "AirlineCode": "AA",
                            "Comment": "VIxxxxxxxxxxxx1111",
                            "Commission": "10.00",
                            "Fare": "1168",
                            "FOPMethod": "CX",
                            "MCOType": "AC",
                            "Tax": "72.40",
                            "TranControlNbr": "0251207588"
                        },
                        "AirlineTicketCoupons": [
                            {
                                "ClassOfService": "E",
                                "CouponNumber": 1,
                                "CouponStatus": "USED",
                                "EndCityCode": "DEN",
                                "FlightNumber": "5894",
                                "RateCode": "CQ690",
                                "StartCityCode": "IAD",
                                "StartDateLocal": "2020-12-11T15:54:18.000-00:00",
                                "Vendor": "AA"
                            },
                            {
                                "ClassOfService": "E",
                                "CouponNumber": 2,
                                "CouponStatus": "OPEN",
                                "EndCityCode": "LAX",
                                "FlightNumber": "6617",
                                "RateCode": "CQ210",
                                "StartCityCode": "IAD",
                                "StartDateLocal": "2020-12-16T15:54:18.000-00:00",
                                "Vendor": "UA"
                            }
                        ],
                        "AirlineTicketFareBreakups": [
                            {
                                "BaseFare": 275.55,
                                "Currency": "USD",
                                "EndCityCode": "SFO",
                                "IsRefundable": true,
                                "StartCityCode": "LAX",
                                "TotalFare": 355.55,
                                "Vendor": "AA"
                            }
                        ],
                        "BaseFare": 1168,
                        "BaseFareCurrency": "USD",
                        "ComparisonFare": 1,
                        "ComparisonFareCurrency": "USD",
                        "DateCreatedUtc": "2020-11-04T20:54:19.000+00:00",
                        "DateModifiedUtc": "2020-11-04T20:54:19.000+00:00",
                        "Endorsements": "NOREF/NOEXCH.  NO VALUE AFTER FIRST FLT DATE",
                        "IssueDateTime": "2020-11-03T00:00:00.000-00:00",
                        "IssuingIataAgencyNumber": 82494313,
                        "IssuingPseudoCity": "13H1",
                        "LinearFareConstructor": "THIS IS A LINEAR FARE CONSTRUCTOR IAD-LAX",
                        "PassengerName": "DoverRN MSN CNBC/Emil",
                        "PlatingCarrierNumericCode": "001",
                        "PlatingControlNumber": "0251207588",
                        "ProgramCarrierCode": "AA",
                        "ProgramMembershipNumber": "387519635",
                        "RecordLocator": "A88372",
                        "Taxes": [
                            {
                                "TaxAmount": 58.4,
                                "TaxAuthority": "USA",
                                "TaxName": "Silly Air Ticket Tax",
                                "TaxRate": 0.57,
                                "TaxType": "US"
                            },
                            {
                                "TaxAmount": 5,
                                "TaxAuthority": "USA",
                                "TaxName": "SillyAir Ticket Tax",
                                "TaxRate": 0.57,
                                "TaxType": "AY"
                            },
                            {
                                "TaxAmount": 9,
                                "TaxAuthority": "USA",
                                "TaxName": "Silly Air Ticket Tax",
                                "TaxRate": 0.57,
                                "TaxType": "XF"
                            },
                            {
                                "TaxAmount": 3.6,
                                "TaxAuthority": "USA",
                                "TaxName": "Silly Air Ticket Tax",
                                "TaxRate": 0.57,
                                "TaxType": "ZP"
                            }
                        ],
                        "Ticketless": false,
                        "TotalFare": 1244,
                        "TotalFareCurrency": "USD"
                    },
                    {
                        "AccountingLine": {
                            "AirlineCode": "AA",
                            "Comment": "VIxxxxxxxxxxxx1111",
                            "Commission": "10.00",
                            "Fare": "2341",
                            "FOPMethod": "CX",
                            "MCOType": "AC",
                            "Tax": "131.05",
                            "TranControlNbr": "0137973356"
                        },
                        "AirlineTicketCoupons": [
                            {
                                "ClassOfService": "E",
                                "CouponNumber": 1,
                                "CouponStatus": "EXCH",
                                "EndCityCode": "DEN",
                                "FlightNumber": "5894",
                                "RateCode": "CQ690",
                                "StartCityCode": "IAD",
                                "StartDateLocal": "2020-12-11T15:54:18.000-00:00",
                                "Vendor": "AA"
                            },
                            {
                                "ClassOfService": "E",
                                "CouponNumber": 2,
                                "CouponStatus": "EXCH",
                                "EndCityCode": "LAX",
                                "FlightNumber": "6617",
                                "RateCode": "CQ210",
                                "StartCityCode": "IAD",
                                "StartDateLocal": "2020-12-16T15:54:18.000-00:00",
                                "Vendor": "UA"
                            }
                        ],
                        "AirlineTicketExchanges": [
                            {
                                "Amount": 100,
                                "AppliedSegment1": 1,
                                "AppliedSegment2": 1,
                                "Currency": "EUR",
                                "DateModifiedUtc": "2020-11-04T20:54:19.000+00:00",
                                "OldRecordLocator": "DEL324",
                                "PlatingCarrierNumericCode": "001",
                                "PlatingControlNumber": "0137973356"
                            }
                        ],
                        "AirlineTicketFareBreakups": [
                            {
                                "BaseFare": 255.55,
                                "Currency": "USD",
                                "EndCityCode": "SFO",
                                "IsRefundable": true,
                                "StartCityCode": "JFK",
                                "TotalFare": 375.55,
                                "Vendor": "AA"
                            }
                        ],
                        "BaseFare": 2341,
                        "BaseFareCurrency": "USD",
                        "ComparisonFare": 1,
                        "ComparisonFareCurrency": "USD",
                        "DateCreatedUtc": "2020-11-04T20:54:19.000+00:00",
                        "DateModifiedUtc": "2020-11-04T20:54:19.000+00:00",
                        "Endorsements": "NOREF/NOEXCH.  NO VALUE AFTER FIRST FLT DATE",
                        "IssueDateTime": "2020-11-02T00:00:00.000-00:00",
                        "IssuingIataAgencyNumber": 96085218,
                        "IssuingPseudoCity": "13H1",
                        "LinearFareConstructor": "THIS IS A LINEAR FARE CONSTRUCTOR IAD-LAX",
                        "PassengerName": "DoverRN MSN CNBC/Emil",
                        "PlatingCarrierNumericCode": "001",
                        "PlatingControlNumber": "0137973356",
                        "ProgramCarrierCode": "AA",
                        "ProgramMembershipNumber": "387519635",
                        "RecordLocator": "A21012",
                        "Taxes": [
                            {
                                "TaxAmount": 117.05,
                                "TaxAuthority": "USA",
                                "TaxName": "Silly Air Ticket Tax",
                                "TaxRate": 0.57,
                                "TaxType": "US"
                            },
                            {
                                "TaxAmount": 5,
                                "TaxAuthority": "USA",
                                "TaxName": "SillyAir Ticket Tax",
                                "TaxRate": 0.57,
                                "TaxType": "AY"
                            },
                            {
                                "TaxAmount": 9,
                                "TaxAuthority": "USA",
                                "TaxName": "Silly Air Ticket Tax",
                                "TaxRate": 0.57,
                                "TaxType": "XF"
                            },
                            {
                                "TaxAmount": 3.6,
                                "TaxAuthority": "USA",
                                "TaxName": "Silly Air Ticket Tax",
                                "TaxRate": 0.57,
                                "TaxType": "ZP"
                            }
                        ],
                        "Ticketless": false,
                        "TotalFare": 2475.65,
                        "TotalFareCurrency": "USD"
                    }
                ]
            },
            "BookingOwner": "ConcurTravel",
            "BookingSource": "Manual",
            "Charges": {
                "Fixed": [
                    {
                        "Amount": 2,
                        "Currency": "USD",
                        "Description": "Booking fee",
                        "IsPrimary": false,
                        "SemanticsCode": "OTHER",
                        "SemanticsVendorType": "C",
                        "Vendor": "LH",
                        "VendorChargeCode": "BF2000"
                    }
                ],
                "Percent": [
                    {
                        "Amount": 7,
                        "Currency": "USD",
                        "Description": "Tax",
                        "IsPrimary": false,
                        "SemanticsCode": "VAT",
                        "SemanticsVendorType": "H",
                        "VendorChargeCode": "Mars tax"
                    }
                ]
            },
            "DateBookedLocal": "2020-10-30T15:54:18.000-00:00",
            "DateCreatedUtc": "2020-11-04T20:54:19.000+00:00",
            "DateModifiedUtc": "2020-11-04T20:54:19.000+00:00",
            "Delivery": {
                "AddressLine1": "200 Street 1",
                "AddressLine2": "Street 2",
                "City": "London",
                "Country": "UK",
                "Email": "pasenger@keto.com",
                "Latitude": 51.320000,
                "LocationAdditionalDetails": "<Kiosk KioskLocation=\"On concourse\"/>",
                "LocationDesc": "You will find the Self-service Ticket machine located at the front of the station. Aberystwyth Station is open 24 hours a day.",
                "LocationName": "London Euston",
                "Longitude": 0.500000,
                "PhoneNumber": "(703)837.6100",
                "ReferenceNumber": "RBK9G589",
                "State": "MA",
                "Type": "Kiosk",
                "Zip": "32432"
            },
            "FormOfPaymentName": "CorporateAccount",
            "FormOfPaymentType": "CA",
            "IsGhostCard": false,
            "PassPrograms": [
                {
                    "Amount": 2,
                    "Name": "North America - Tango Plus 200 credits",
                    "Type": "Credits",
                    "UserFirstName": "Peter",
                    "UserLastName": "Neagle"
                }
            ],
            "Passengers": [
                {
                    "FirstNameNumber": 0,
                    "FrequentTravelerPrograms": {
                        "FrequentFlyer": [
                            {
                                "FrequentFlyerNumber": "1234567890"
                            },
                            {
                                "AirlineVendor": "BA",
                                "FrequentFlyerNumber": "01234567890"
                            }
                        ]
                    },
                    "LastNameNumber": 1,
                    "NameFirst": "Emil",
                    "NameLast": "Dover",
                    "NameSuffix": "RN MSN CNBC",
                    "NameTitle": "Mr.",
                    "TextName": "DoverRN MSN CNBC/Emil"
                },
                {
                    "FirstNameNumber": 1,
                    "FrequentTravelerPrograms": {
                        "FrequentFlyer": [
                            {
                                "FrequentFlyerNumber": "1234567890"
                            },
                            {
                                "AirlineVendor": "BA",
                                "FrequentFlyerNumber": "01234567890"
                            },
                            {
                                "FrequentFlyerNumber": "ABC12345",
                                "Status": "Gold",
                                "StatusExpirationDate": "2020-12-31T00:00:00.000-00:00"
                            }
                        ]
                    },
                    "LastNameNumber": 1,
                    "NameFirst": "Ben",
                    "NameLast": "Esch",
                    "NameMiddle": "Dwayne",
                    "NameRemark": "FINANCE",
                    "NameSuffix": "III",
                    "NameTitle": "Mr.",
                    "TextName": "EschIII/BenDwayne"
                }
            ],
            "PhoneNumbers": [
                {
                    "Description": "Residence",
                    "PassengerRPH": 0,
                    "PhoneNumber": "703-837-6100"
                }
            ],
            "RecordLocator": "BCC52120201104205418831",
            "Remarks": {
                "TripLinkRemarks": [
                    {
                        "TripLinkRemark": [
                            {
                                "Text": "TESTING"
                            }
                        ]
                    }
                ]
            },
            "Segments": {
                "Air": [
                    {
                        "AircraftCode": "767",
                        "Cabin": "E",
                        "CarbonEmissionLbs": 5470,
                        "CarbonModel": 158,
                        "CheckedBaggage": "Extra bag $25",
                        "ClassOfService": "E",
                        "ConfirmationNumber": "N1985820201104205418865",
                        "DateCreatedUtc": "2020-11-04T20:54:19.000+00:00",
                        "DateModifiedUtc": "2020-11-04T20:54:19.000+00:00",
                        "Duration": 140,
                        "EndCityCode": "DEN",
                        "EndDateLocal": "2020-12-11T18:14:18.000-00:00",
                        "EndDateUtc": "2020-12-12T01:14:18.000+00:00",
                        "EndGate": "68",
                        "EndTerminal": "D",
                        "FlightNumber": "5894",
                        "FrequentTravelerId": "387519635",
                        "IsUpgradeAllowed": true,
                        "LegId": 1,
                        "Meals": "Kebabs",
                        "Miles": 986,
                        "NumStops": 0,
                        "OperatedByFlightNumber": "8606",
                        "OperatedByVendor": "DL",
                        "OperatedByVendorName": "Delta",
                        "Seats": [
                            {
                                "PassengerRph": 0,
                                "SeatNumber": "12A",
                                "Status": "X"
                            },
                            {
                                "PassengerRph": 1,
                                "SeatNumber": "13B"
                            }
                        ],
                        "SpecialInstructions": "Nothing special",
                        "StartCityCode": "IAD",
                        "StartDateLocal": "2020-12-11T15:54:18.000-00:00",
                        "StartDateUtc": "2020-12-11T20:54:18.000+00:00",
                        "StartGate": "47",
                        "StartTerminal": "A",
                        "Status": "HK",
                        "UpgradedDateTime": "2020-12-11T15:54:18.000-00:00",
                        "Vendor": "AA",
                        "VendorName": "American Airlines"
                    },
                    {
                        "AircraftCode": "767",
                        "Cabin": "E",
                        "CheckedBaggage": "Extra bag $25",
                        "ClassOfService": "E",
                        "ConfirmationNumber": "N7192620201104205418868",
                        "DateCreatedUtc": "2020-11-04T20:54:19.000+00:00",
                        "DateModifiedUtc": "2020-11-04T20:54:19.000+00:00",
                        "Duration": 81,
                        "EndCityCode": "LAX",
                        "EndDateLocal": "2020-12-16T17:15:18.000-00:00",
                        "EndDateUtc": "2020-12-17T01:15:18.000+00:00",
                        "EndGate": "20",
                        "EndTerminal": "D",
                        "FlightNumber": "6617",
                        "FrequentTravelerId": "1815857656",
                        "IsUpgradeAllowed": true,
                        "LegId": 2,
                        "Meals": "Kebabs",
                        "Miles": 663,
                        "NumStops": 2,
                        "OperatedByFlightNumber": "4047",
                        "OperatedByVendor": "UA",
                        "OperatedByVendorName": "United",
                        "Seats": [
                            {
                                "PassengerRph": 0,
                                "SeatNumber": "12A",
                                "Status": "X"
                            },
                            {
                                "PassengerRph": 1,
                                "SeatNumber": "13B"
                            }
                        ],
                        "SpecialInstructions": "Nothing special",
                        "StartCityCode": "IAD",
                        "StartDateLocal": "2020-12-16T15:54:18.000-00:00",
                        "StartDateUtc": "2020-12-16T20:54:18.000+00:00",
                        "StartGate": "86",
                        "StartTerminal": "A",
                        "Status": "HK",
                        "UpgradedDateTime": "2020-12-11T15:54:18.000-00:00",
                        "Vendor": "UA",
                        "VendorName": "United"
                    }
                ]
            },
            "WebAddresses": [
                {
                    "Description": "Work Email",
                    "Format": "E",
                    "PassengerRPH": 0,
                    "Type": "WRK",
                    "WebAddress": "Michaell@concur.com"
                }
            ]
        },
        {
            "AgencyName": "Outtask Travel Apollo",
            "AgencyPCC": "C4I",
            "BookingOwner": "ConcurTravel",
            "BookingSource": "Manual",
            "Charges": {
                "Fixed": [
                    {
                        "Amount": 4,
                        "Currency": "USD",
                        "Description": "Booking fee",
                        "IsPrimary": false,
                        "SemanticsCode": "OTHER",
                        "SemanticsVendorType": "C",
                        "Vendor": "LH",
                        "VendorChargeCode": "BF2000"
                    }
                ],
                "Percent": [
                    {
                        "Amount": 1,
                        "Currency": "USD",
                        "Description": "Tax",
                        "IsPrimary": false,
                        "SemanticsCode": "VAT",
                        "SemanticsVendorType": "H",
                        "VendorChargeCode": "Mars tax"
                    }
                ]
            },
            "DateBookedLocal": "2020-10-30T15:54:18.000-00:00",
            "DateCreatedUtc": "2020-11-04T20:54:19.000+00:00",
            "DateModifiedUtc": "2020-11-04T20:54:19.000+00:00",
            "Delivery": {
                "AddressLine1": "200 Street 1",
                "AddressLine2": "Street 2",
                "City": "London",
                "Country": "UK",
                "Email": "pasenger@keto.com",
                "Latitude": 51.320000,
                "LocationAdditionalDetails": "<Kiosk KioskLocation=\"On concourse\"/>",
                "LocationDesc": "You will find the Self-service Ticket machine located at the front of the station. Aberystwyth Station is open 24 hours a day.",
                "LocationName": "London Euston",
                "Longitude": 0.500000,
                "PhoneNumber": "(703)837.6100",
                "ReferenceNumber": "RBK9G589",
                "State": "MA",
                "Type": "Kiosk",
                "Zip": "32432"
            },
            "FormOfPaymentName": "CorporateAccount",
            "FormOfPaymentType": "CA",
            "PassPrograms": [
                {
                    "Amount": 2,
                    "Name": "North America - Tango Plus 200 credits",
                    "Type": "Credits",
                    "UserFirstName": "Peter",
                    "UserLastName": "Neagle"
                }
            ],
            "Passengers": [
                {
                    "FirstNameNumber": 0,
                    "LastNameNumber": 0,
                    "NameFirst": "Ann",
                    "NameLast": "Esch",
                    "NamePrefix": "Sgt.",
                    "NameRemark": "ABC*123",
                    "NameSuffix": "III",
                    "NameTitle": "Mr.",
                    "TextName": "EschIII/AnnSgt."
                }
            ],
            "PhoneNumbers": [
                {
                    "Description": "Agency",
                    "PhoneNumber": "703-837-6106",
                    "Type": "W"
                }
            ],
            "RecordLocator": "K5589420201104205418911",
            "Segments": {},
            "WebAddresses": [
                {
                    "Description": "Work Email",
                    "Format": "E",
                    "PassengerRPH": 0,
                    "Type": "WRK",
                    "WebAddress": "Michaell@concur.com"
                }
            ]
        },
        {
            "AgencyName": "Outtask Travel Apollo",
            "AgencyPCC": "C4I",
            "BookingOwner": "ConcurTravel",
            "BookingSource": "Manual",
            "Charges": {
                "Fixed": [
                    {
                        "Amount": 4,
                        "Currency": "USD",
                        "Description": "Booking fee",
                        "IsPrimary": false,
                        "SemanticsCode": "OTHER",
                        "SemanticsVendorType": "C",
                        "Vendor": "LH",
                        "VendorChargeCode": "BF2000"
                    }
                ],
                "Percent": [
                    {
                        "Amount": 3,
                        "Currency": "USD",
                        "Description": "Tax",
                        "IsPrimary": false,
                        "SemanticsCode": "VAT",
                        "SemanticsVendorType": "H",
                        "VendorChargeCode": "Mars tax"
                    }
                ]
            },
            "DateBookedLocal": "2020-10-30T15:54:18.000-00:00",
            "DateCreatedUtc": "2020-11-04T20:54:19.000+00:00",
            "DateModifiedUtc": "2020-11-04T20:54:19.000+00:00",
            "Delivery": {
                "AddressLine1": "200 Street 1",
                "AddressLine2": "Street 2",
                "City": "London",
                "Country": "UK",
                "Email": "pasenger@keto.com",
                "Latitude": 51.320000,
                "LocationAdditionalDetails": "<Kiosk KioskLocation=\"On concourse\"/>",
                "LocationDesc": "You will find the Self-service Ticket machine located at the front of the station. Aberystwyth Station is open 24 hours a day.",
                "LocationName": "London Euston",
                "Longitude": 0.500000,
                "PhoneNumber": "(703)837.6100",
                "ReferenceNumber": "RBK9G589",
                "State": "MA",
                "Type": "Kiosk",
                "Zip": "32432"
            },
            "FormOfPaymentName": "CorporateAccount",
            "FormOfPaymentType": "CA",
            "PassPrograms": [
                {
                    "Amount": 2,
                    "Name": "North America - Tango Plus 200 credits",
                    "Type": "Credits",
                    "UserFirstName": "Peter",
                    "UserLastName": "Neagle"
                }
            ],
            "Passengers": [
                {
                    "FirstNameNumber": 1,
                    "LastNameNumber": 0,
                    "NameFirst": "Ann",
                    "NameLast": "Dover",
                    "NamePrefix": "Sgt.",
                    "NameRemark": "FINANCE",
                    "NameTitle": "Mr.",
                    "TextName": "Dover/AnnSgt."
                }
            ],
            "PhoneNumbers": [
                {
                    "Description": "Business",
                    "PhoneNumber": "800 401 8412",
                    "Type": "B"
                }
            ],
            "RecordLocator": "TF630420201104205418911",
            "Remarks": {
                "TripLinkRemarks": [
                    {
                        "TripLinkRemark": [
                            {
                                "Text": "MID OFFICE STUFF"
                            },
                            {
                                "Text": "TESTING"
                            },
                            {
                                "Text": "TO TEST THE MID OFFICE REMARKS"
                            }
                        ]
                    }
                ]
            },
            "Segments": {
                "Ride": [
                    {
                        "CancellationPolicy": "Call 20 minutes in advance to avoid charge",
                        "ConfirmationNumber": "C74450820201104205418911",
                        "Currency": "USD",
                        "DateCreatedUtc": "2020-11-04T20:54:19.000+00:00",
                        "DateModifiedUtc": "2020-11-04T20:54:19.000+00:00",
                        "DropoffInstructions": "Open door and jump out when speed is below 10 MPH",
                        "Duration": 2,
                        "EndAddress": "DCA",
                        "EndAddress2": "Thomas Ave & Abingon",
                        "EndCity": "Alexandria",
                        "EndCityCode": "DCA",
                        "EndCountry": "US",
                        "EndDateLocal": "2020-12-16T13:54:18.000-00:00",
                        "EndDateUtc": "2020-12-16T18:54:18.000+00:00",
                        "EndLatitude": 38.852843,
                        "EndLongitude": -77.038536,
                        "EndPostalCode": "22202",
                        "EndState": "VA",
                        "MeetingInstructions": "Meet by hot dog stand in front of building",
                        "Miles": 10,
                        "Name": "Yellow Cab",
                        "NumPersons": 2,
                        "NumberOfHours": 0.03333333333333333,
                        "PhoneNumber": "703-837-6100",
                        "PickupInstructions": "Pickup at given address",
                        "Rate": 24,
                        "RateDescription": "Hourly rate",
                        "RateType": "H",
                        "StartAddress": "209 Madison Street",
                        "StartCity": "Alexandria",
                        "StartCityCode": "DCA",
                        "StartCountry": "US",
                        "StartDateLocal": "2020-12-16T11:54:18.000-00:00",
                        "StartDateUtc": "2020-12-16T16:54:18.000+00:00",
                        "StartLatitude": 38.814098,
                        "StartLongitude": -77.040939,
                        "StartPostalCode": "22314",
                        "StartState": "VA",
                        "TimeZoneId": 25,
                        "Vendor": "$R",
                        "VendorName": "RideCharge"
                    }
                ]
            },
            "WebAddresses": [
                {
                    "Description": "Home AIM",
                    "Format": "I",
                    "Type": "RES",
                    "WebAddress": "mloreOuttask"
                }
            ]
        }
    ],
    "Comments": "Generated from - MakeRandomItineraryWithSpecifiedSegment: 401722883",
    "CustomAttributes": [
        {
            "Data": "1914163392_1398750079_63698747",
            "DataType": "Enumeration",
            "DisplayOnItinerary": true,
            "DisplayTitle": "Title_1882786037",
            "Name": "Custom_1047320375"
        },
        {
            "Data": "2144949539_499322633_1732005039",
            "DataType": "Enumeration",
            "DisplayOnItinerary": false,
            "DisplayTitle": "Title_559871572",
            "Name": "Custom_1726736195"
        },
        {
            "Data": "683267112_1599532776_1875679442",
            "DataType": "Enumeration",
            "DisplayOnItinerary": true,
            "DisplayTitle": "Title_119690786",
            "ExternalId": 1088610323,
            "Name": "Custom_1899779539"
        },
        {
            "Data": "56781286_861560873_80874171",
            "DataType": "Enumeration",
            "DisplayOnItinerary": true,
            "DisplayTitle": "Title_390352466",
            "Name": "Custom_1579191469"
        },
        {
            "Data": "2067714888_1442184475_1016439405",
            "DataType": "String",
            "DisplayOnItinerary": true,
            "DisplayTitle": "Title_1544667785",
            "Name": "Custom_1166600630"
        },
        {
            "Data": "351251522_246017323",
            "DataType": "Numeric",
            "DisplayOnItinerary": true,
            "DisplayTitle": "Title_19093583",
            "Name": "Custom_750631891"
        },
        {
            "Data": "821749202_364197364_762362918",
            "DataType": "Enumeration",
            "DisplayOnItinerary": false,
            "DisplayTitle": "Title_1467115321",
            "ExternalId": 1986175686,
            "Name": "Custom_2007441754"
        },
        {
            "Data": "473097600_978534217",
            "DataType": "Numeric",
            "DisplayOnItinerary": true,
            "DisplayTitle": "Title_1137473737",
            "Name": "Custom_1832693806"
        },
        {
            "Data": "1679301535_433494967_1252049254",
            "DataType": "Enumeration",
            "DisplayOnItinerary": true,
            "DisplayTitle": "Title_15390255",
            "Name": "Custom_1100573803"
        }
    ],
    "DateBookedLocal": "2020-10-30T15:54:18.000-00:00",
    "DateCreatedUtc": "2020-11-04T20:54:19.000+00:00",
    "DateModifiedUtc": "2020-11-04T20:54:51.026+00:00",
    "Description": "Trip from somewhere to somewhere else 506643842",
    "EndDateLocal": "2020-12-16T17:15:18.000-00:00",
    "EndDateUtc": "2020-12-17T01:15:18.000+00:00",
    "id": "https://us.api.concursolutions.com/travel/v4/trips/08d019f6-8c7e-5e96-bbf4-04726ac5def2",
    "ItinLocator": "gWutRRSrKhRhhY9lx0GUfP1YhfAXDTBtYwFTA$pKU",
    "ProjectName": "Big Project # 43534534",
    "StartDateLocal": "2020-12-11T15:54:18.000-00:00",
    "StartDateUtc": "2020-12-11T20:54:18.000+00:00",
    "TravelRequestId": "TR98318081",
    "TripName": "My Random Trip #266255879",
    "TripStatus": 0,
    "UserLoginId": "itintrips@coreprofiletesting.com"
}

Schemas

Main Itinerary Level Elements

Name Type Format Description
BookedByFirstName string - The first name of the person who booked the trip.
BookedByLastName string - The last name of the person who booked the trip.
BookedVia string - The booking method for the trip.
Bookings array Booking Element A parent element that contains a Booking child element for each booking associated with this itinerary.
CancelComments string - The comments provided if the itinerary is cancelled. Maximum length: 256 characters
ClientLocator string - Represents the unique identifier of the trip in an external (non-SAP Concur) system. Maximum length: 32 characters
Comments string - Comments for this itinerary. Maximum length: 512 characters
CustomAttributes array Custom Attribute Element A parent element that contains a CustomAttribute child element for all custom attributes configured for trip level that may or not may not have values set.
DateBookedLocal dateTime YYYY-MM-DDThh:mm:ss The date the trip was booked, in the local time of the booking's location.
DateCreatedUtc dateTime YYYY-MM-DDThh:mm:ss The date that this trip was created, in UTC.
DateModifiedUtc dateTime YYYY-MM-DDThh:mm:ss The UTC date that this trip was last modified.
Description string - The trip description. Maximum length: 512 characters
EndDateLocal dateTime YYYY-MM-DDThh:mm:ss The end date of the trip in the ending location’s timezone.
EndDateUtc dateTime YYYY-MM-DDThh:mm:ss The end date of the trip, in UTC.
HasOpenBookingPassive boolean true/false The trip has TripLink passive segments.
ID string - The unique identifier for the itinerary, this is included in the event and is used for the callback to get details of the trip.
IsPersonal boolean true/false If true, the booking is a personal trip.
ItinLocator string - The itinerary locator. This element is now deprecated and only supported for backward compatibility.
ProjectName string - The associated project name for the trip. Maximum length: 255 characters
StartDateLocal dateTime YYYY-MM-DDThh:mm:ss The start date of the trip in the starting location’s timezone.
StartDateUtc dateTime YYYY-MM-DDThh:mm:ss The start date of the trip, in UTC.
TravelRequestID string - SAP Concur Travel Request ID.
TripLinkLocator string - SAP Concur TripLink ID.
TripName string - Name of the trip. Maximum length: 255 characters
TripStatus string - The status of the itinerary. Supported values: 0 - Confirmed, 1 - Ticketed by agent, 2 - Cancelled
UserLoginID string - The user's login to the SAP Concur system.

Booking Element

Name Type Format Description
AgencyName string - The name of the agency.
AgencyPCC string - Pseudo city code for the agency.
AirfareQuotes array Airfare Quotes Element List of stored airfare quotes. This parent element has a Quote child element for each airfare quote. The Quote parent element contains the Airfare Quotes Child Elements.
AirlineTickets type Airline Ticket Child Element List of airline tickets. This parent element contains Airline Tickets Child Elements.
BookingOwner string - Indicates the tool that supplied the booking to Concur Travel.
BookingSource string - The name of the booking source for this booking. A booking source is a textual name the system uses to track where a booking took place.
Charges type Charge Detail Element List of charges for this booking.
DateBookedLocal dateTime YYYY-MM-DDThh:mm:ss The date the booking was created, in the local time of the booking's location.
DateCreatedUtc dateTime YYYY-MM-DDThh:mm:ss The date that this booking was created, in UTC.
DateModifiedUtc dateTime YYYY-MM-DDThh:mm:ss The UTC date that this booking was last modified.
Delivery type Delivery Element The method this booking was delivered.
FormOfPaymentName string - The name of the form of payment for the booking.
FormOfPaymentType string - The type of the form of payment.
IsGhostCard boolean true/false If true, the payment was made using a shared corporate credit card.
ItinSourceName string TravelSupplier The itinerary source.
LastTicketDateUtc dateTime YYYY-MM-DDThh:mm:ss UTC timestamp of the latest ticket.
MiscChargeOrders array Misc Charge Order Element This parent element has a MiscellaneousChargeOrder child element for each included miscellaneous charge. The MiscellaneousChargeOrder parent element contains Miscellaneous Charge Order Child Elements.
Passengers array Passenger Element Contains a Passenger child element for each included passenger.
PassPrograms array Pass Program Element This parent element has Pass Program child elements for each pass program associated with the booking.
PhoneNumbers array Phone Number Data Element List of phone numbers associated with this booking. This parent element has a PhoneNumberData child element for each phone number associated with the booking. The PhoneNumberData parent element has the following child elements: PassengerRPH, PhoneNumber, Type, and Description.
RailPayments type [Rail Payment Child Element](#schema-rail-payment-base) List of rail payments associated with rail segments in this booking. It has the following child elements: RailPayment that represents the payment information for a rail booking and RailAdjustment for the amount adjusted for a rail booking.
RecordLocator string - The unique identifier for a booking. This is often six alphanumeric characters, but can have other formats depending on the booking source.
Remarks type Remark Element Remarks on the booking.
Segments type Segment Element List of segments in this booking. The child elements included in this element vary depending on whether a TMC, SAP Concur client, third-party developer, or TripLink supplier is requesting the itinerary details: For TMCs, clients, and third-party developers, the Segments element contains one or more Air, Car, Hotel, Dining, Ride, Rail, Parking, or Travel parent elements. For TripLink suppliers, the Segments element contains one or more Air, Car, Hotel, or Ride parent elements.
TicketMailingAddress string - The mailing address for the booked ticket, if available.
TicketPickupLocation string - The pick-up location for the booked ticket, if available.
TicketPickupNumber string - The confirmation number for the booked ticket, if available.
WaitListSegments type Wait List Segment Element The segments that the traveler is waitlisted for this booking.
Warning array Warning Element The warnings associated with the booking.
WebAddresses array Web Address Element List of web addresses such as emails, pick-up URLs, and so on associated with this booking.

Airfare Quotes Element

Name Type Format Description
AirlineCharges array Charge Detail Element This parent element contains a Fixed and a Percent child element for each fixed charge and percent of fixed charge associated with this airfare quote. For information about these child elements, see the Fixed Elements table and the Percent Elements table.
BaseFare decimal - The base fare of the airfare quote.
BaseFareCurrency string - The 3-letter ISO 4217 currency code for the base fare.
BaseFareNuc decimal - The base fare in NUC.
BaseFareNucCurrency string - The 3-letter ISO 4217 currency code for the base fare in NUC.
DateCreatedUtc dateTime YYYY-MM-DDThh:mm:ss The date that this airfare quote was created, in UTC.
DateModifiedUtc dateTime YYYY-MM-DDThh:mm:ss The UTC date that this airfare quote was last modified.
Endorsements string - Notes from the airline if it endorses the ticket as acceptable on a different airline.
IssueByDate dateTime YYYY-MM-DDThh:mm:ss The date the quote must be issued by.
TotalFare decimal - The total price of the booking.
TotalFareCurrency string - The 3-letter ISO 4217 currency code for the total fare.

Airline Ticket Child Element

Name Type Format Description
AirlineAdjustment array Airline Adjustment Element Any adjustment made to the booking. For information about the child elements of AirlineAdjustmentType, see the AirlineAdjustmentType Elements table.
AirlineTicket array Airline Ticket Element The manual airline ticket for the booking. For information about the child elements of ManualAirlineTicket, see the ManualAirlineTicket Elements table.
ManualAirlineTicket array Manual Airline Ticket Element The airline ticket for the booking. For information about the child elements of AirlineTicket, see the AirlineTicket Elements table.

Delivery Element

Name Type Format Description
AddressLine1 string - The delivery street address.
AddressLine2 string - The delivery street address.
City string - The city of the delivery address.
Country string - The country of the delivery address.
Email string - The email of the delivery contact.
Latitude decimal - The latitude of the delivery address.
LocationAdditionalDetails string - Additional information about the delivery location.
LocationDesc string - The description of the delivery location.
LocationName string - The name of the delivery location.
Longitude decimal - The longitude of the delivery address.
PhoneNumber string - The phone number of the delivery contact.
ReferenceNumber string - The reference number for the delivery.
State string - The state of the delivery address.
Type string - The type of delivery address.
Zip string - The postal code or zip code of the delivery address.

Miscellaneous Charge Order Element

Name Type Format Description
DateCreatedUtc dateTime YYYY-MM-DDThh:mm:ss The date the charge order was created, in UTC.
DateModifiedUtc dateTime YYYY-MM-DDThh:mm:ss The date the charge order was last modified, in UTC.
IssueDate dateTime YYYY-MM-DDThh:mm:ss The date the charge order was issued.
PlatingCarrierNumericCode string - The three-digit ticket number that indicates the airline code. Examples: 001 - American, 005 - Continental, 006 - Delta, 012 - Northwest
PlatingControlNumber string - Ten digits of the ticket number that indicates the ticket control number.
TotalAmount decimal - The total amount of charge orders for the ticket.
TotalAmountCurrency string - The 3-letter ISO 4217 currency code for the total charge order amount.

Pass Program Element

Name Type Format Description
Amount decimal - The program amount.
Name string - The program name.
Type string - The program type.
UserFirstName string - The first name of the passenger.
UserLastName string - The last name of the passenger.

Passenger Element

Name Type Format Description
City string - The city of the passenger's address.
Country string - The country of the passenger's address.
FirstNameNumber integer - The number of characters in the passenger's first name.
FrequentTravelerProgram type Frequent Traveler Program Element Passenger's loyalty programs.
LastNameNumber number - The number of characters in the passenger's last name.
NameFirst string - The first name of the passenger.
NameLast string - The last name of the passenger.
NameMiddle string - The middle name of the passenger.
NamePrefix string - The name prefix of the passenger.
NameRemark string - Additional details about the passenger's name.
NameSuffix string - The name suffix of the passenger.
NameTitle string - The title of the passenger.
PostalCode string - The postal code or zip code of the passenger's address.
State string - The state of the passenger's address.
StreetAddress string - The passenger's street address.
StreetAddress2 string - The passenger's street address.
TextName string - The user's full name as entered in the booking tool if different from the name in the database.

Phone Number Data Element

Name Type Format Description
Description string - The description for the phone number.
PassengerRPH integer - Indicates the passenger to whom this phone number belongs.
PhoneNumber string - The passenger's phone number.
Type string - The type of phone number.

Rail Payment Child Element

Name Type Format Description
RailAdjustment array Rail Adjustment Element The amount adjusted for a rail booking. For information about the RailAdjustment child elements, see the Rail Adjustment Element table.
RailPayment array Rail Payment Element The payment information for a rail booking. For information about the RailPayment child elements, see the Rail Payment Element table.

Remark Element

Name Type Format Description
TripLinkRemarks array TripLink Remarks Element TripLink remarks.
Name Type Format Description
TripLinkRemark array TripLink Remark Element A TripLink remark.
Name Type Format Description
Text string - TripLink remarks.

Segment Element

Name Type Format Description
Air array Air Segment Element Air segment.
Car array Car Segment Element Car segment.
Dining array Dining Segment Element Dining segment.
Hotel array Hotel Segment Element Hotel segment.
Parking array Parking Segment Element Parking segment.
Rail array Rail Segment Element Rail segment.
Ride array Ride Segment Element Ride segment.
Travel array Travel Segment Element Travel segment.

Wait List Segment Element

Name Type Format Description
SegmentOption array Segment Option Item Element Air segments on which a user is waitlisted.

Warning Element

Name Type Format Description
Code array - Warning code.
Text array - Warning text.
Type array - Warning type.

Charge Detail Element

Name Type Format Description
Fixed array Fixed Charge Element The fixed charges.
Percent array Percent of Fixed Charges Element The percent of fixed charges.
Rate array Rate Charge Element The rate for the booking.
RateWithAllowance array Rate With Allowance Charge Element The rate for the booking, including any travel allowances.

Airline Adjustment Element

Name Type Format Description
AddCollectAmount decimal - Specifies the net fare (i.e. the actual fare paid) if it differs from the total fare for the ticket due to applicable credits from the original exchanged ticket.
AdjustmentDateTime dateTime YYYY-MM-DDThh:mm:ss Local timestamp for the adjustment.
AdjustmentDateTimeUTC dateTime YYYY-MM-DDThh:mm:ss UTC timestamp for the adjustment.
AdjustmentType string - Type of adjustment.
AirlineCharges array Charge Detail Element Charges associated to the adjustment.
DateCreatedUtc dateTime YYYY-MM-DDThh:mm:ss UTC timestamp of adjustment creation.
DateModifiedUtc dateTime YYYY-MM-DDThh:mm:ss UTC timestamp of adjustment modification.
PassengerName string - Name of passenger.
PlatingCarrierNumericCode string - The three-digit ticket number that indicates the airline code. Examples: 001 - American, 005 - Continental, 006 - Delta, 012 - Northwest
PlatingControlNumber string - Ten digits of the ticket number that indicates the ticket control number.
RecordLocator string - The unique identifier for a booking. This is often six alphanumeric characters, but can have other formats depending on the booking source.
Taxes array Tax Element Taxes on the adjustment.
TotalAdjustment decimal - Total cost of adjustment.
TotalAdjustmentCurrency string - Currency of the adjustment.

Airline Ticket Element

Name Type Format Description
AccountingLine type Accounting Line Element The accounting line on the airline ticket.
AddCollectAmount decimal - Specifies the net fare (i.e. the actual fare paid) if it differs from the total fare for the ticket due to applicable credits from the original exchanged ticket.
AirlineCharges array Charge Detail Element Charges associated to the ticket.
AirlineTicketCoupons array Airline Ticket Coupon Element A list of coupons for this ticket. This parent element has an AirlineTicketCoupon child element for each coupon associated with this airline ticket. For information about these child elements, see the Airline Ticket Coupon Element table.
AirlineTicketExchanges array Airline Ticket Exchanges Element A list of exchanges for this ticket. This parent element has an AirlineTicketExchange child element for each exchange associated with this airline ticket. For information about these child elements, see the Airline Ticket Exchange Element table.
AirlineTicketFareBreakups array Airline Ticket Fare Breakups Element A list of fare breakups for this ticket. This parent element has an AirlineTicketFareBreakup child element for each fare breakup associated with this airline ticket. For information about these child elements, see the Airline Ticket Fare Breakup Element table.
BaseFare decimal - Fare without any tax penalties.
BaseFareCurrency string - The 3-letter ISO 4217 currency code for the base fare.
BaseFareNuc decimal - The base fare in NUC.
BaseFareNucCurrency string - The 3-letter ISO 4217 currency code for the base fare in NUC.
ComparisonFare decimal - A baseline fare provided by the TMC for contractual reference.
ComparisonFareCurrency string - The 3-letter ISO 4217 currency code for the comparison fare.
DateCreatedUtc dateTime YYYY-MM-DDThh:mm:ss UTC timestamp of ticket creation.
DateModifiedUtc dateTime YYYY-MM-DDThh:mm:ss UTC timestamp of ticket modification.
Endorsements string - Notes from the airline if it endorses the ticket as acceptable on a different airline.
InvoiceNumber string - Invoice associated with the ticket.
IssueDateTime dateTime YYYY-MM-DDThh:mm:ss Timestamp of ticket issuing.
IssueDateTimeUTC dateTime YYYY-MM-DDThh:mm:ss UTC timestamp of ticket issuing.
IssuingIataAgencyNumber integer - IATA number of agency that issued the ticket.
IssuingPseudoCity string - Pseudo city code of the issuing ticket agency.
LinearFareConstructor string A breakdown of the total fare.
MasterTicketNumber string - The ticket number.
NameReference string - Not used.
PassengerName string - Airline ticket holder's full name.
PlatingCarrierNumericCode string - The three-digit ticket number that indicates the airline code. Examples: 001 - American, 005 - Continental, 006 - Delta, 012 - Northwest
PlatingControlNumber string - Ten digits of the ticket number that indicates the ticket control number.
ProgramCarrierCode string - The airline vendor code for the program.
ProgramMembershipNumber string - The membership number for the program.
RecordLocator string - The unique identifier for a booking. This is often six alphanumeric characters, but can have other formats depending on the booking source.
SabreDkNumber string - Appears only if a booking was created by the relavent GDS.
Taxes array Tax Element Taxes applied to the airline ticket.
Ticketless boolean true/false If true, the ticket is ticketless.
TicketType string - The type of the ticket.
TotalFare decimal - Total cost of ticket.
TotalFareCurrency string - The 3-letter ISO 4217 currency code of ticket.
TourIdentifier string - Special negotiated fare.

Manual Airline Ticket Element

Name Type Format Description
AirlineCharges array Charge Detail Element Charges associated to the ticket.
BaseFare decimal - Fare without any tax penalties.
BaseFareCurrency string - The 3-letter ISO 4217 currency code for the base fare.
DateCreatedUtc dateTime YYYY-MM-DDThh:mm:ss UTC timestamp of ticket creation.
DateModifiedUtc dateTime YYYY-MM-DDThh:mm:ss UTC timestamp of ticket modification.
Taxes array Tax Element Taxes on the ticket.
TotalFare decimal - Total cost of ticket.
TotalFareCurrency string - The 3-letter ISO 4217 currency code of ticket.

Fixed Charge Element

Name Type Format Description
Amount decimal - The total amount for the rate for the booking.
Currency string - The 3-letter ISO 4217 currency code for the total amount.
Description string - The description for the rate.
IsPaid boolean true/false If true, the rate has been paid.
IsPrimary boolean true/false If true, the rate is the primary rate. If one of the rates is the actual rate and the rest are penalties, the actual rate should be set as IsPrimary. Only one charge in a set should be set as primary.
SemanticsCode string - Indicates the charge category for the line item. Refer to the Semantics Codes table for more information.
SemanticsVendorType string - The vendor type. Supported values: H - Hotel, C - Car, A - Air, G - Ground, R - Rail
StartDateLocal dateTime YYYY-MM-DDThh:mm:ss The start date of the booking, in the user's local time.
Vendor string - The vendor for the booking charge.
VendorChargeCode string - The vendor's code for the charge.

Percent of Fixed Charges Element

Name Type Format Description
Amount decimal - The total amount for the rate for the booking.
Currency string - The 3-letter ISO 4217 currency code for the total amount.
Description string - The description for the rate.
IsPaid boolean true/false If true, the rate has been paid.
IsPrimary boolean true/false If true, the rate is the primary rate. If one of the rates is the actual rate and the rest are penalties, the actual rate should be set as IsPrimary. Only one charge in a set should be set as primary.
SemanticsCode string - Indicates the charge category for the line item. Refer to the Semantics Codes table for more information.
SemanticsVendorType string - The vendor type. Supported values: H - Hotel, C - Car, A - Air, G - Ground, R - Rail
StartDateLocal dateTime YYYY-MM-DDThh:mm:ss The start date of the booking, in the user's local time.
Vendor string - The vendor for the booking charge.
VendorChargeCode string - The vendor's code for the charge.

Rate Charge Element

Name Type Format Description
Amount decimal - The total amount for the rate for the booking.
Currency string - The 3-letter ISO 4217 currency code for the total amount.
Description string - The description for the rate.
IsPaid boolean true/false If true, the rate has been paid.
IsPrimary boolean true/false If true, the rate is the primary rate. If one of the rates is the actual rate and the rest are penalties, the actual rate should be set as IsPrimary. Only one charge in a set should be set as primary.
NumUnits decimal - The number of units expected for the charge.
PerUnit string - The unit of measure for the charge. Example: DAY, WEEK, MONTH
SemanticsCode string - Indicates the charge category for the line item. Refer to the Semantics Codes table for more information.
SemanticsVendorType string - The vendor type. Supported values: H - Hotel, C - Car, A - Air, G - Ground, R - Rail
StartDateLocal dateTime YYYY-MM-DDThh:mm:ss The start date of the booking, in the user's local time.
Vendor string - The vendor for the booking charge.
VendorChargeCode string - The vendor's code for the charge.

Rate With Allowance Charge Element

Name Type Format Description
AllowanceAmount decimal - The cost of overage fees when the allowance is exceeded. For example, if the allowance is 5000 miles, the cost could be $0.02 per mile. The overage must be in the same currency as the basic rate.
AllowanceIsUnlimited boolean true/false If true, the allowance is unlimited.
AllowanceNumUnits decimal - The number of units for the allowance associated with the charge.
AllowanceUnit string - The unit of measure for the allowance associated with the charge.
Amount decimal - The total amount for the rate for the booking.
Currency string - The 3-letter ISO 4217 currency code for the total amount.
Description string - The description for the rate.
IsPaid boolean true/false If true, the rate has been paid.
IsPrimary boolean true/false If true, the rate is the primary rate. If one of the rates is the actual rate and the rest are penalties, the actual rate should be set as IsPrimary. Only one charge in a set should be set as primary.
NumUnits decimal - The number of units expected for the charge.
PerUnit string - The unit of measure for the charge. Example: DAY, WEEK, MONTH
SemanticsCode string - Indicates the charge category for the line item. Refer to the Semantics Codes table for more information.
SemanticsVendorType string - The vendor type. Supported values: H - Hotel, C - Car, A - Air, G - Ground, R - Rail
StartDateLocal dateTime YYYY-MM-DDThh:mm:ss The start date of the booking, in the user's local time.
Vendor string - The vendor for the booking charge.
VendorChargeCode string - The vendor's code for the charge.

Rail Adjustment Element

Name Type Format Description
AdjustmentDateTime dateTime YYYY-MM-DDThh:mm:ss Timestamp for the adjustment.
AdjustmentDateTimeUTC dateTime YYYY-MM-DDThh:mm:ss UTC timestamp for the adjustment.
AdjustmentType string - Type of adjustment.
DateCreatedUtc dateTime YYYY-MM-DDThh:mm:ss UTC timestamp for adjustment creation.
DateModifiedUtc dateTime YYYY-MM-DDThh:mm:ss UTC timestamp for adjustment modification.
RailCharges array Charge Detail Element List of charges for this rail booking.
Taxes array Tax Element Taxes on the adjustment.
TicketDocumentIdentifier string - Not used.
TotalAdjustment decimal - Total cost of the adjustment.
TotalAdjustmentCurrency string - The 3-letter ISO 4217 currency code for the total adjustment.

Rail Payment Element

Name Type Format Description
BaseFare decimal - Fare without any tax penalties.
BaseFareCurrency string - The 3-letter ISO 4217 currency code for the base fare.
DateCreatedUtc dateTime YYYY-MM-DDThh:mm:ss The date the quote was created, in UTC.
DateModifiedUtc dateTime YYYY-MM-DDThh:mm:ss The date the quote was last modified, in UTC.
IncludesVAT boolean true/false If true, includes the value add tax.
IssueByDate dateTime YYYY-MM-DDThh:mm:ss The date the quote must be issued by.
IssueDateTime dateTime YYYY-MM-DDThh:mm:ss Timestamp of quote being issued.
IssueDateTimeUTC dateTime YYYY-MM-DDThh:mm:ss UTC timestamp of quote being issued.
RailCharges array Charge Detail Element List of charges for this rail booking.
TaxInvoice boolean true/false If true, the charge is a legal tax invoice.
Taxes array Tax Element Taxes on the payment.
TicketDocumentIdentifier string - Not used.
TicketType string - Type of the ticket.
TotalFare decimal - The total price of the booking.
TotalFareCurrency string - The 3-letter ISO 4217 currency code for the total fare.
VatApplicable boolean true/false If true, value add tax is applicable.

Air Segment Element

Name Type Format Description
AircraftCode string - The code for the aircraft type.
Bags string - The number of bags included in the booking.
Cabin string - The section of the airplane for the booking.
CancellationNumber string - The cancellation number from the vendor. This field should be set when you cancel a segment.
CancellationPolicy string - The cancellation policy from the vendor.
CarbonEmissionLbs decimal - The pounds of carbon emission for this booking.
CarbonModel integer - The model used to calculate the carbon emissions.
Charges type Charge Detail Element List of charges for this booking.
CheckedBaggage string - Whether the booking includes checked baggage.
ClassOfService string - The class of the booking.
ConfirmationNumber string - The record locator or confirmation number for the flight from the airline.
DateCancelledUtc dateTime YYYY-MM-DDThh:mm:ss The date the booking was cancelled, in UTC.
DateCreatedUtc dateTime YYYY-MM-DDThh:mm:ss The date the booking was created, in UTC.
DateModifiedUtc dateTime YYYY-MM-DDThh:mm:ss The date the booking was modified, in UTC.
Duration integer - The duration of the booked flight.
EndCityCode string - The IATA airport code for the end city of the booking.
EndDateLocal dateTime YYYY-MM-DDThh:mm:ss The booking ending time and date, in the booking location's local time.For TripLink suppliers: The time portion of this value will be set to T00:00:00 if the request is from a TripLink - Open Booking Air supplier that does not own the booking.
EndDateUtc dateTime YYYY-MM-DDThh:mm:ss The booking ending time and date, in UTC. For TripLink suppliers: The time portion of this value will be set to T00:00:00 if the request is from a TripLink - Open Booking Air supplier that does not own the booking.
EndGate string - The arrival gate for the booking. For TripLink suppliers: Will not appear in the response if the request is from a TripLink - Open Booking Air supplier that does not own the booking.
EndTerminal string - The arrival terminal for the booking.For TripLink suppliers: Will not appear in the response if the request is from a TripLink - Open Booking Air supplier that does not own the booking.
ETicket string E/Y/N Whether the booking has an e-ticket.
FlightNumber string - The flight number for the booking.
FrequentTravelerId string - The traveler’s ID for the frequent traveler reward program.
IsOpenSegment boolean true/false If true, the segment is open.
IsPreferredVendor boolean true/false If true, the airline is marked as a preferred property by the company.
IsUpgradeAllowed boolean true/false If true, the booking can be upgraded.
LegID string - The leg ID of the booking. Leg IDs do not change on a connection. For each unique leg ID in the trip, all flights subsequent to the first segment with the same leg ID are connections.
Meals string - The meals included in the booking.
Miles integer - The number of miles included in the booking.
Notes string - Additional details about the booking.
NumStops unsignedByte - The number of stops in the booking.
OpenSegment string - Additional information about the open segment.
OperatedByFlightNumber string - Flight number provided by the airline operating the flight on behalf of the booked airline.
OperatedByVendor string - The airline operating the flight on behalf of the booked airline.
OperatedByVendorName string - The name of the airline operating the flight on behalf of the booked airline.
Remarks type Remark Element Remarks on the segment.
RuleViolations array Rule Violation Element The list of rule violations associated with the itinerary. This parent element contains a Rule Violation child element for each associated rule violation.
Seats array Air Seat Element The seats for the booking. This parent element contains an AirSeat element for each included seat. For more information, see the Air Seat Elements table later on this page.
Services string - The services included in the booking.
SpecialInstructions string - Additional instructions regarding the booking. Maximum length: 256
StartCityCode string - The IATA airport code for the starting address for the booking.
StartDateLocal dateTime YYYY-MM-DDThh:mm:ss The booking starting time and date, in the booking location's local time. For TripLink suppliers: The time portion of this value will be set to T00:00:00 if the request is from a TripLink - Open Booking Air supplier that does not own the booking.
StartDateUtc dateTime YYYY-MM-DDThh:mm:ss The booking starting time and date, in UTC. For TripLink suppliers: The time portion of this value will be set to T00:00:00 if the request is from a TripLink - Open Booking Air supplier that does not own the booking.
StartGate string - The departure gate for the booking. For TripLink suppliers: Will not appear in the response if the request is from a TripLink - Open Booking Air supplier that does not own the booking.
StartTerminal string - The departure terminal for the booking. For TripLink suppliers: Will not appear in the response if the request is from a TripLink - Open Booking Air supplier that does not own the booking.
Status string - The GDS based booking status for the segment. Example: HK, HL, BK
TimeZone string Olson or Windows Time Zones The time zone of the booking.
TimeZoneID integer - The ID for the time zone of the booking.
UpgradedDateTime dateTime YYYY-MM-DDThh:mm:ss The date and time the booking was upgraded.
Vendor string - The two-letter GDS vendor code
VendorFlags string - Not used
VendorName string - The name of the vendor.

Car Segment Element

Name Type Format Description
AirCondition string - The character code that indicates if car has air conditioner. Supported values: R - AC, N - No AC
Body string - The body style of the car. Supported values: B - Two-door sedan, D - Four-door sedan, F - Four-wheel drive, J - All terrain, K - Truck, L - Limo, P - Pickup, R - recreation, S - Sport, T - Convertible, V - Van, W - Wagon/Estate, X - Special
CancellationNumber string - The cancellation number from the vendor. This field should be set when you cancel a segment.
Charges type Charge Detail Element List of charges for this booking.
Class string - Character code to indicate the class of the car. Varies by vendor. Supported values: C - Compact, E - Economy, F - Full size, I - Intermediate, L - Luxury, M - Mini, P - Premium, S - Standard, X - Special
ConfirmationNumber string - The confirmation number from the vendor.
Currency string - The 3-letter ISO 4217 currency code for the booking.
DailyRate decimal - The daily rate for the booking.
DateCancelledUtc dateTime YYYY-MM-DDThh:mm:ss The date the booking was cancelled, in UTC.
DateCreatedUtc dateTime YYYY-MM-DDThh:mm:ss The date the booking was created, in UTC.
DateModifiedUtc dateTime YYYY-MM-DDThh:mm:ss The date the booking was modified, in UTC.
DiscountCode string - The discount code used by the company or TMC to get a discounted rate.
DropoffCollectionAddress1 string - The AddressLine1 for the dropoff address when the rental service offers dropoff.
DropoffCollectionAddressType string - The type of address for the dropoff address when the rental service offers dropoff.
DropoffCollectionCategory string - The category of dropofff address when the rental service offers dropoff.
DropoffCollectionCityCode string - The IATA airport code for the dropoff address when the rental service offers dropoff.
DropoffCollectionCity string - City for the dropoff address when the rental service offers dropoff.
DropoffCollectionCountry string - The country for the dropoff address when the rental service offers dropoff.
DropoffCollectionLatitude string - The latitude for the dropoff address when the rental service offers dropoff.
DropoffCollectionLongitude string - The longitude for the dropoff address when the rental service offers dropoff.
DropoffCollectionNumber string - The number for the dropoff address when the rental service offers dropoff.
DropoffCollectionPhoneNumber string - The phone number for the dropoff address when the rental service offers dropoff.
DropoffCollectionPostalCode string - The postal code for the dropoff address when the rental service offers dropoff.
DropoffCollectionState string - The state for the dropoff address when the rental service offers dropoff.
EndAddress2 string - The ending address for the booking.
EndAddress string - The ending address for the booking.
EndCityCode string - The IATA airport code for the ending address for the booking.
EndCity string - The ending address for the booking.
EndCloseTime string - The closing time for the dropoff location.
EndCountry string - The ending address for the booking.
EndDateLocal dateTime YYYY-MM-DDThh:mm:ss The booking ending time and date, in the booking location's local time.
EndDateUtc dateTime YYYY-MM-DDThh:mm:ss The booking ending time and date, in UTC.
EndLatitude string - The latitude for the ending location of the booking.
EndLongitude string - The longitude for the ending location of the booking.
EndOpenTime string - The opening time of the dropoff location.
EndPhoneNumber string - The phone number of the dropoff location.
EndPostalCode string - The ending address for the booking.
EndState string - The ending address for the booking.
IsGhostCard boolean true/false Indicates if a payment was made using a shared corporate credit card.
IsPreferredVendor integer - If true, the rental service is marked as a preferred service by the company.
IsUpgradeAllowed boolean true/false If true, the booking can be upgraded.
Notes string - Additional information about the booking.
NumCars unsignedByte - The number of cars rented.
NumPersons unsignedByte - The number of people including the driver that the rental is for.
PhoneNumber string - The phone number for the user.
PickupDeliveryAddress1 string - The AddressLine1 for the pick-up address when the rental service offers pick-up.
PickupDeliveryAddressType string - The type of address for the pick-up address when the rental service offers pick-up.
PickupDeliveryCategory string - The category for the pick-up address when the rental service offers pick-up.
PickupDeliveryCityCode string - The IATA airport code for the pick-up address when the rental service offers pick-up.
PickupDeliveryCity string - The city for the pick-up address when the rental service offers pick-up.
PickupDeliveryCountry string - The country for the pick-up address when the rental service offers pick-up.
PickupDeliveryLatitude string - The latitude for the pick-up address when the rental service offers pick-up.
PickupDeliveryLongitude string - The longitude for the pick-up address when the rental service offers pick-up.
PickupDeliveryNumber string - The number for the pick-up address when the rental service offers pick-up.
PickupDeliveryPhoneNumber string - The phone number for the pick-up address when the rental service offers pick-up.
PickupDeliveryPostalCode string - The postal code for the pick-up address when the rental service offers pick-up.
PickupDeliveryState string - The state for the pick-up address when the rental service offers pick-up.
RateCode string - The rate code for the booking.
RateType string - The rate type for the booking.
Remarks type Remark Element Remarks on the segment.
SpecialEquipment string - Any special equipment required by the renter.
SpecialInstructions string - Additional instructions regarding the booking. Maximum length: 256
StartAddress2 string - The starting address for the booking.
StartAddress string - The starting address of the booking.
StartCityCode string - The IATA airport code for the starting address for the booking.
StartCity string - The starting address for the booking.
StartCloseTime string - The closing time for the pick-up location.
StartCountry string - The starting address for the booking.
StartDateLocal dateTime YYYY-MM-DDThh:mm:ss The booking starting time and date, in the booking location's local time.
StartDateUtc dateTime YYYY-MM-DDThh:mm:ss The booking starting time and date, in UTC.
StartLatitude string - The latitude for the starting location of the booking.
StartLocation string - The starting location of the booking.
StartLongitude string - The longitude for the starting location of the booking.
StartOpenTime string - The opening time for the pick-up location.
StartPostalCode string - The starting address for the booking.
StartState string - The starting address for the booking.
Status string - The booking status.
TimeZone string Olson or Windows Time Zones The time zone of the booking.
TimeZoneID integer - The ID for the time zone of the booking.
TotalRate decimal - The total rate amount of the booking.
Transmission string - The character code that indicates if the car has auto-transmission. Supported values: A - Auto, M - Manual
UpgradedDateTime dateTime YYYY-MM-DDThh:mm:ss The date and time the booking was upgraded.
VendorName string - The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary.
VendorFlags string - Not used
Vendor string - The two letter GDS vendor code.

Dining Segment Element

Name Type Format Description
CancellationNumber string - The cancellation number from the vendor. This field should be set when you cancel a segment.
Charges type Charge Detail Element List of charges for this booking.
ConfirmationNumber string - The confirmation number from the vendor.
DateCancelledUtc dateTime YYYY-MM-DDThh:mm:ss The date the booking was cancelled, in UTC.
DateCreatedUtc dateTime YYYY-MM-DDThh:mm:ss The date the booking was created, in UTC.
DateModifiedUtc dateTime YYYY-MM-DDThh:mm:ss The date the booking was modified, in UTC.
EndDateLocal dateTime YYYY-MM-DDThh:mm:ss The booking ending time and date, in the booking location's local time.
EndDateUtc dateTime YYYY-MM-DDThh:mm:ss The booking ending time and date, in UTC.
FrequentTravelerId string - The loyalty program ID for the user.
IsPreferredVendor integer - If true, the restaurant is marked as a preferred property by the company.
IsUpgradeAllowed boolean true/false If true, the booking can be upgraded.
Name string - The name of the restaurant. Maximum length: 80
Notes string - Additional information about the booking.
NumPersons unsignedByte - The number of persons for the booking.
PhoneNumber string - The restaurant phone number.
Remarks type Remark Element Remarks on the segment.
ReservationID string - The ID for restaurant reservation.
StartAddress string - The restaurant address. Maximum length: 80
StartAddress2 string - The restaurant address. Maximum length: 80
StartCity string - The restaurant address. Maximum length: 50
StartCountry string - The restaurant address.
StartDateLocal dateTime YYYY-MM-DDThh:mm:ss The booking starting time and date, in the booking location's local time.
StartDateUtc dateTime YYYY-MM-DDThh:mm:ss The booking starting time and date, in UTC.
StartLatitude string - The latitude of the restaurant.
StartLongitude string - The longitude of the restaurant.
StartPostalCode string - The restaurant address. Maximum length: 24
StartState string - The restaurant address. Maximum length: 50
Status string - The status of the segment.
TimeZone string Olson or Windows Time Zones The time zone of the booking.
TimeZoneID integer - The ID for the time zone of the booking.
UpgradedDateTime dateTime YYYY-MM-DDThh:mm:ss The date and time the booking was upgraded.
Vendor string - The two letter GDS vendor code.
VendorFlags string - Not used
VendorName string - The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary.

Hotel Segment Element

Name Type Format Description
Breakfast boolean true/false Indicates if breakfast is included with hotel stay.
CancellationNumber string - The cancellation number from the vendor. This field should be set when you cancel a segment.
CancellationPolicy string - The cancellation policy from the vendor.
Charges type Charge Detail Element List of charges for this booking.
CheckinTime string - The check in time for the hotel booking.
CheckoutTime string - The check out time for the hotel booking.
ConfirmationNumber string - The confirmation number from the vendor.
Currency string - The 3-letter ISO 4217 currency code for the booking.
DailyRate decimal - Average per day rate for the hotel. If the rate varies over the duration, it can be specified using the charges model.
DateCancelledUtc dateTime YYYY-MM-DDThh:mm:ss The date the booking was cancelled, in UTC.
DateCreatedUtc dateTime YYYY-MM-DDThh:mm:ss The date the booking was created, in UTC.
DateModifiedUtc dateTime YYYY-MM-DDThh:mm:ss The date the booking was modified, in UTC.
DirectBill boolean true/false Indicates the hotel will bill the company directly.
DiscountCode string - The discount code for the booking.
Email string - Email for the hotel.
EndDateLocal dateTime YYYY-MM-DDThh:mm:ss The booking ending time and date, in the booking location's local time.
EndDateUtc dateTime YYYY-MM-DDThh:mm:ss The booking ending time and date, in UTC.
EquipmentCode string - Not used.
FaxNumber string - Fax number for the hotel.
FrequentTravelerId string - The traveler’s ID for the frequent traveler reward program.
HotelPropertyID string - The hotel's property ID.
IncludedCustomAmenities string - Not used.
IsGhostCard boolean true/false Indicates if a payment was made using a shared corporate credit card.
IsPreferredVendor integer - If true, the hotel is marked as a preferred property by the company.
IsUpgradeAllowed boolean true/false If true, the booking can be upgraded.
ModificationCode string - The code for the modification to the booking.
Name string - The hotel name for the booking.
Notes string - Additional information about the booking.
NumPersons unsignedByte - The number of people the booking is for.
NumRooms unsignedByte - The number of rooms the booking is for.
Parking boolean true/false Indicates if the hotel reservation includes parking.
PartnerMembershipId string - The membership ID of the partner associated with the booking.
PassiveType string - The type of the booking.
PhoneNumber string - The phone number for the booking.
RateAccess string - The rate access for the booking.
RateCode string - The rate code for the booking.
RateType string - The rate type for the booking.
RoomDescription string - The room description for the booking. Maximum length: 200
RoomType string - The room type for the booking.
SpecialInstructions string - Additional instructions regarding the booking. Maximum length: 256
StartAddress string - The starting address of the booking.
StartAddress2 string - The starting address for the booking.
StartCity string - The starting address for the booking.
StartCityCode string - The IATA airport code for the starting address for the booking.
StartCountry string - The starting address for the booking.
StartDateLocal dateTime YYYY-MM-DDThh:mm:ss The booking starting time and date, in the booking location's local time.
StartDateUtc dateTime YYYY-MM-DDThh:mm:ss The booking starting time and date, in UTC.
StartLatitude string - The latitude for the starting location of the booking.
StartLongitude string - The longitude for the starting location of the booking.
StartPostalCode string - The starting address for the booking.
StartState string - The starting address for the booking.
Status string - The booking status.
TimeZone string Olson or Windows Time Zones The time zone of the booking.
TimeZoneID integer - The ID for the time zone of the booking.
TotalRate string - The total rate amount of the booking.
UpgradedDateTime dateTime YYYY-MM-DDThh:mm:ss The date and time the booking was upgraded.
Vendor string - The two letter GDS vendor code.
VendorFlags string - Not used
VendorName string - The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary.
WiFi boolean true/false Indicates if hotel reservation includes WIFI.

Parking Segment Element

Name Type Format Description
CancellationNumber string - The cancellation number from the vendor. This field should be set when you cancel a segment.
Charges type Charge Detail Element List of charges for this booking.
ClassOfService string - The class of the booking.
ConfirmationNumber string - The confirmation number from the vendor.
Currency string - The 3-letter ISO 4217 currency code for the booking.
DateCancelledUtc dateTime YYYY-MM-DDThh:mm:ss The date the booking was cancelled, in UTC.
DateCreatedUtc dateTime YYYY-MM-DDThh:mm:ss The date the booking was created, in UTC.
DateModifiedUtc dateTime YYYY-MM-DDThh:mm:ss The date the booking was modified, in UTC.
EndDateLocal dateTime YYYY-MM-DDThh:mm:ss The booking ending time and date, in the booking location's local time.
EndDateUtc dateTime YYYY-MM-DDThh:mm:ss The booking ending time and date, in UTC.
FrequentTravelerId string - The traveler’s ID for the frequent traveler reward program.
IsPreferredVendor integer If true, the parking company is marked as preferred by the company.
IsUpgradeAllowed boolean true/false If true, the booking can be upgraded.
Name string - Name of the parking facility.
Notes string - Additional information about the booking.
OperatedByVendor string - The operating vendor of the booking.
ParkingLocationId string - The location of the parking booking.
PhoneNumber string - The parking phone number.
Pin string - The PIN number for the booking.
RateCode string - The vendor's code for the rate of the booking.
Remarks type Remark Element Remarks on the segment.
StartAddress string - The starting address of the booking.
StartAddress2 string - The starting address of the booking.
StartCity string - The starting address of the booking.
StartCityCode string - The IATA airport code for the starting city of the booking.
StartCountry string - The starting address of the booking.
StartDateLocal dateTime YYYY-MM-DDThh:mm:ss The starting date of travel for this segment, in the local time of to the starting point.
StartDateUtc dateTime YYYY-MM-DDThh:mm:ss The starting date of travel for this segment, in UTC.
StartLocation string - The parking location.
StartPostalCode string - The starting address of the booking. Maximum length: 24
StartState string - The starting address of the booking. Maximum length: 50
Status string - The booking status.
TimeZone string Olson or Windows Time Zones The time zone of the booking.
TimeZoneID integer - The ID for the time zone of the booking.
TotalRate string - The total rate amount of the booking.
UpgradedDateTime dateTime YYYY-MM-DDThh:mm:ss The date and time the booking was upgraded.
Vendor string The two letter GDS vendor code.
VendorFlags string - Not used
VendorName string - The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary.

Rail Segment Element

Name Type Format Description
Amenities string - The booked amenities.
Cabin string - The cabin identifier.
CancellationNumber string - The cancellation number from the vendor. This field should be set when you cancel a segment.
CarbonEmissionLbs decimal - The pounds of carbon emission for this booking.
CarbonModel integer - The model used to calculate the carbon emissions.
Charges type Charge Detail Element List of charges for this booking.
ClassOfService string - The class of the booking.
ConfirmationNumber string - The confirmation number from the vendor.
Currency string - The 3-letter ISO 4217 currency code for the booking.
DateCancelledUtc dateTime YYYY-MM-DDThh:mm:ss The date the booking was cancelled, in UTC.
DateCreatedUtc dateTime YYYY-MM-DDThh:mm:ss The date the booking was created, in UTC.
DateModifiedUtc dateTime YYYY-MM-DDThh:mm:ss The date the booking was modified, in UTC.
DiscountCode string - The discount code for the booking.
Duration integer - The duration of the trip booked.
EndCity string - The end city for the rail trip.
EndCityCode string - The IATA airport code for the end city of the trip.
EndCountry string - The country code for the booking.
EndDateLocal dateTime YYYY-MM-DDThh:mm:ss The booking ending time and date, in the booking location's local time.
EndDateUtc dateTime YYYY-MM-DDThh:mm:ss The booking ending time and date, in UTC.
EndLatitude string - The latitude of the ending point of the booking.
EndLongitude integer - The longitude of the ending point of the booking.
EndPlatform string - The ending platform location of the booking.
EndRailStation string - The code for the ending station of the booking.
EndRailStationName string - The name of the ending station of the booking.
EndState string - The end state/province for the rail trip.
Eticket integer - The e-ticket number.
FrequentTravelerId string - The traveler’s ID for the frequent traveler reward program.
IsPreferredVendor integer - If true, the rail carrier is marked as a preferred rail carrier by the company.
IsUpgradeAllowed boolean true/false If true, the booking can be upgraded.
LegId string - The trip leg ID.
Meals string - The booked meals.
Miles integer - The number of miles booked.
Notes string - Additional information about the booking.
NumPersons unsignedByte - The number of persons booked for the trip.
NumStops unsignedByte - The number of stops in the booking.
OperatedByTrainNumber string - The train identifier of the operating vendor of the booked trip.
OperatedByVendor string - The operating vendor of the booked trip.
RateCode string - The vendor's code for the rate of the booking.
Remarks type Remark Element Remarks on the segment.
RouteRestrictCode string - The code to restrict the route of the booking.
Seats array Rail Seat Element The booked seats. This parent element contains a Rail Seat element for each included seat. For more information, see the Rail Seat Elements table.
SpecialInstructions string - The instructions for the booking. Maximum length: 256
StartCity string - The starting city of the booking.
StartCityCode string - The IATA airport code for the starting city of the booking.
StartCountry string - The starting country of the booking.
StartDateLocal dateTime YYYY-MM-DDThh:mm:ss The starting date of travel for this segment, in the local time of to the starting point.
StartDateUtc dateTime YYYY-MM-DDThh:mm:ss The starting date of travel for this segment, in UTC.
StartLatitude string - The latitude of the starting location of the booking.
StartLongitude string - The longitude of the starting location of the booking.
StartPlatform string - The starting platform location of the booking.
StartRailStation string - The code of the starting station of the booking.
StartRailStationName string - The name of the starting station of the booking.
StartState string - The start state/province for the rail trip.
Status string - The booking status.
TimeZone string Olson or Windows Time Zones The time zone of the booking.
TimeZoneID integer - The ID for the time zone of the booking.
TotalRate decimal - The total rate amount of the booking.
TrainNumber string - The number for the booked train.
TrainTypeCode string - The code for the type of train used in the booking.
TrainTypeName string - The name of the type of train used in the booking.
TransportMode string - The transport mode of the booking.
UpgradedDateTime dateTime YYYY-MM-DDThh:mm:ss The date and time the booking was upgraded.
Vendor string - The two letter GDS vendor code.
VendorFlags string - Not used
VendorName string - The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary.
WagonNumber string - The wagon number of the train car.

Ride Element

Name Type Format Description
CancellationNumber string - The cancellation number from the vendor. This field should be set when you cancel a segment.
CancellationPolicy string - The cancellation policy from the vendor.
Charges type Charge Detail Element List of charges for this booking.
ConfirmationNumber string - The confirmation number from the vendor.
Currency string - The 3-letter ISO 4217 currency code for the booking.
DateCancelledUtc dateTime YYYY-MM-DDThh:mm:ss The date the booking was cancelled, in UTC.
DateCreatedUtc dateTime YYYY-MM-DDThh:mm:ss The date the booking was created, in UTC.
DateModifiedUtc dateTime YYYY-MM-DDThh:mm:ss The date the booking was modified, in UTC.
DropoffInstructions string - Instructions regarding the booking.
Duration integer - The duration of the booking.
EndAddress string - The ending address of the booking.
EndAddress2 string - The ending address of the booking.
EndCity string - The ending address of the booking.
EndCityCode string - The ending IATA airport code of the booking.
EndCountry string - The ending address of the booking.
EndDateLocal dateTime YYYY-MM-DDThh:mm:ss The booking ending time and date, in the booking location's local time.
EndDateUtc dateTime YYYY-MM-DDThh:mm:ss The booking ending time and date, in UTC.
EndLatitude string - The latitude for the ending location of the booking.
EndLocationCode string - The ending location code of the booking.
EndLongitude string - The longitude of the ending point of the booking.
EndPostalCode string - The ending address of the booking.
EndState string - The ending address of the booking.
IsGhostCard boolean true/false Indicates if a payment was made using a shared corporate credit card.
IsPreferredVendor integer - If true, the ride vendor is marked as a preferred ride vendor by the company.
IsUpgradeAllowed boolean true/false If true, the booking can be upgraded.
MeetingInstructions string - The instructions for the meeting location of the booking.
Miles integer - The number of miles for the booking.
Name string - The name on the booking.
Notes string - Additional information about the booking.
NumPersons unsignedByte - The number of people included in the booking.
NumberOfHours double - The number of hours of the booking.
OperatedByVendor string - The operated by vendor for the booking.
PassiveCityCode string - The passive city code of the booking.
PhoneNumber string - The ride vendor phone number.
PickupInstructions string - Instructions regarding the booking.
ProviderFeedback string - Feedback from the provider.
Rate string - The rate for the booking.
RateDescription string - The rate description for the booking.
RateNotes string - The rate notes for the booking.
RateType string - The rate type for the booking.
Remarks type Remark Element Remarks on the segment.
ReservationID string - The booking vendor’s reservation ID.
SpecialInstructions string - The special instructions for the ride. Maximum length: 256
StartAddress string - The starting address of the booking.
StartAddress2 string - The starting address of the booking.
StartCity string - The starting address of the booking.
StartCityCode string - The starting IATA airport code of the booking.
StartCountry string - The starting address of the booking.
StartDateLocal dateTime YYYY-MM-DDThh:mm:ss The booking starting time and date, in the booking location's local time.
StartDateUtc dateTime YYYY-MM-DDThh:mm:ss The booking starting time and date, in UTC.
StartLatitude string The latitude of the booking start location.
StartLocation string - The starting location of the booking.
StartLocationCode string - The code of the starting location of the booking.
StartLocationName string - The name of the starting location of the booking.
StartLongitude string - The longitude of the booking start location.
StartPostalCode string - The starting address of the booking.
StartState string - The starting address of the booking.
TimeZone string Olson or Windows Time Zones The time zone of the booking.
TimeZoneID integer - The ID for the time zone of the booking.
TotalRate decimal - The total rate amount of the booking.
UpgradedDateTime dateTime YYYY-MM-DDThh:mm:ss The date and time the booking was upgraded.
Vendor string - The two letter GDS vendor code. For an unknown vendor, use the code value: $$.
VendorFlags string - Not used
VendorName string - The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary.

Travel Segment Element

Name Type Format Description
CancellationNumber string - The cancellation number from the vendor. This field should be set when you cancel a segment.
Charges type Charge Detail Element List of charges for this booking.
ConfirmationNumber string - The confirmation number from the vendor.
Currency string - The 3-letter ISO 4217 currency code for the booking.
DailyRate decimal - Average per day rate for the booking. If the rate varies over the duration, it can be specified using the charges model.
DateCancelledUtc dateTime YYYY-MM-DDThh:mm:ss The date the booking was cancelled, in UTC.
DateCreatedUtc dateTime YYYY-MM-DDThh:mm:ss The date the booking was created, in UTC.
DateModifiedUtc dateTime YYYY-MM-DDThh:mm:ss The date the booking was modified, in UTC.
EndAddress string - The ending address of the booking.
EndAddress2 string - The ending address of the booking.
EndCity string - The ending address of the booking.
EndCityCode string - The IATA airport code for the ending city of the booking.
EndCountry string - The ending address of the booking.
EndDateLocal dateTime YYYY-MM-DDThh:mm:ss The booking ending time and date, in the booking location's local time.
EndDateUtc dateTime YYYY-MM-DDThh:mm:ss The booking ending time and date, in UTC.
EndLatitude string - The latitude for the ending location of the booking.
EndLocation string - The ending location of the booking.
EndLongitude string - The longitude of the ending point of the booking.
EndPostalCode string - The ending address of the booking.
EndState string - The ending address of the booking.
IsGhostCard boolean true/false Indicates if a payment was made using a shared corporate credit card.
Notes string - Additional information about the booking.
NumPersons unsignedByte - The number of persons booked for the trip.
PhoneNumber string - The booking phone number.
Remarks type Remark Element Remarks on the segment.
SpecialInstructions string - The instructions for the booking. Maximum length: 256
StartAddress string - The starting address of the booking.
StartAddress2 string - The starting address of the booking.
StartCity string - The starting address of the booking.
StartCityCode string - The IATA airport code for the starting city of the booking.
StartCountry string - The starting address of the booking.
StartDateLocal dateTime YYYY-MM-DDThh:mm:ss The starting date of travel for this segment, in the local time of to the starting point.
StartDateUtc dateTime YYYY-MM-DDThh:mm:ss The starting date of travel for this segment, in UTC.
StartLatitude string - The latitude of the booking.
StartLocation string - The start location of the booking.
StartLongitude string - The longitude of the booking.
StartPostalCode string - The starting address of the booking. Maximum length: 24
StartState string - The starting address of the booking. Maximum length: 50
Status string - The booking status.
TimeZone string Olson or Windows Time Zones The time zone of the booking.
TimeZoneID integer - The ID for the time zone of the booking.
TotalRate decimal - The total rate amount of the booking.
TransportMode string - The transport mode of the booking.
Vendor string - The two letter GDS vendor code.
VendorName string - The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary.

Accounting Line Element

Name Type Format Description
AirlineCode string - This is the 2-character IATA code assigned to the airline for which the ticket is issued
AmountPaid string - This should coincide with the amount charged to the form of payment, less any ticket credit application. This amount can also represent a fare difference ("add collect") on an exchanged ticket. Example: original ticket = $100.00, new ticket = $250.00, AmountPaid = $150.00
AmountPaidCurrency string - The 3-letter ISO 4217 currency code of the amount paid.
Ccnumber string - Credit card number used for the accounting line
Comment string - Comments left for the accounting line.
Commission string - This is the amount of commission the agency (TMC) is taking on the ticket. Like most commissions, it should be accounted for in the total cost of the ticket.
CommissionCurrency string - The 3-letter ISO 4217 currency code of the commission.
ExchangedTicketNumber string - The original ticket number in the case where a ticket is being exchanged for another flight/fare.
Fare string - The cost for the flights booked on the ticket.
FareCurrency string - The 3-letter ISO 4217 currency code of the fare.
Fopmethod string - Form of payment method.
IssueDate string - The date the ticket was issued.
McOType string - MCO = Miscellaneous Charge Order. MCOs are used as "virtual ticket numbers" or tracking numbers for agency service fees, as well as residual ticket credits (example: original ticket = $100.00, new ticket = $50.00, Residual/Credit issued as MCO = $50.00)
Tax string - Total tax applied to the airfare.
TaxCurrency string - The 3-letter ISO 4217 currency code for the taxes.
TranControlNbr string - "Transaction Control Number" This is the 10-digit number that follows the plating number on a ticket.
TranPlatingNbr string - "Transaction Plating Number." All IATA-authorized airlines are issued a 3-digit number that designates the airline on the ticket. Examples: 006 = Delta, 001 = American Airlines, 016 = United Airlines.

Air Seat Element

Name Type Format Description
PassengerRph integer - The passenger assigned to the seat.
SeatNumber string - The number of the seat.
Status string - The status for the seat.

Airline Ticket Coupon Element

Name Type Format Description
ClassOfService string - Class of service for the coupon.
CouponNumber integer - ID for the coupon.
CouponStatus string - Status of the coupon.
EndCityCode string - End city code for the coupon.
FlightNumber string - Flight number for the coupon.
NotValidAfterDate dateTime YYYY-MM-DDThh:mm:ss Timestamp for when the coupon is not valid after.
NotValidBeforeDate dateTime YYYY-MM-DDThh:mm:ss Timestamp for when the coupon is not valid before.
RateCode string - The rate code for the coupon.
StartCityCode string - Start city code for the coupon.
StartDateLocal dateTime YYYY-MM-DDThh:mm:ss Local timestamp for when the flight departs.
Status string - Status of the coupon.
TicketDesignator string - A code on airline tickets to indicate what type of discount is applied, such as for a child or infant, or airline employee.
Vendor string - 2 letter vendor code for the coupon.

Airline Ticket Exchanges Element

Name Type Format Description
Amount decimal - Amount exchanged.
AppliedSegment1 integer - Internal use.
AppliedSegment10 integer - Internal use.
AppliedSegment2 unsignedByte - Internal use.
AppliedSegment3 integer - Internal use.
AppliedSegment4 integer - Internal use.
AppliedSegment5 integer - Internal use.
AppliedSegment6 integer - Internal use.
AppliedSegment7 integer - Internal use.
AppliedSegment8 integer - Internal use.
AppliedSegment9 integer - Internal use.
Currency string - The 3-letter ISO 4217 currency code for the ticket.
DateModifiedUtc dateTime YYYY-MM-DDThh:mm:ss The UTC timestamp of ticket exchange modification.
OldRecordLocator string - The unique identifier for a booking. This is often six alphanumeric characters, but can have other formats depending on the booking source.
PlatingCarrierNumericCode string - The three-digit ticket number that indicates the airline code. Examples: 001 - American, 005 - Continental, 006 - Delta, 012 - Northwest
PlatingControlNumber string - Ten digits of the ticket number that indicates the ticket control number.

Airline Ticket Fare Breakups Element

Name Type Format Description
BaseFare decimal - Fare without any tax penalities.
ClassOfService string - Class of fare for the ticket.
Currency string - The 3-letter ISO 4217 currency code
EndCityCode string - End city code for the ticket.
IsRefundable boolean true/false Indicates if the ticket is refundable.
StartCityCode string - Start city code for the ticket.
TotalFare decimal - Total cost of the ticket.
Vendor string - 2 letter vendor code for the ticket fare.

Custom Attribute Element

Name Type Format Description
Data string - The value set for the custom attribute.
DataType string - The type of the custom attribute like numeric, string, etc.
DisplayOnItinerary boolean true/false The condition that determines whether the attribute is displayed on the itinerary.
DisplayTitle string - ignore this - this is the title of the custom attribute to display on the Concur-UI.
ExternalId integer - THe internal reference to the definition of the custom attribute definition.
Name string - Work the Concur Travel Administrator for the company to get a list of configured custom trip attributes (known as Custom Trip Fields in the Concur documentation, not to be confused with Custom Profile fields). This is the name of the custom attribute configured by the admin.

Frequent Traveler Program Element

Name Type Format Description
FrequentFlyer array Frequent Flyer Element Frequent flyer information
RailProgram array Rail Program Element Advantage program information

Frequent Flyer Element

Name Type Format Description
AirlineVendor string - The 2 letter vendor code of the frequent flyer program.
Description string - The program descirption.
DiscountProgramExpirationDate dateTime YYYY-MM-DDThh:mm:ss The date the discount program enrollment expires.
DiscountProgramType string - The type of the discount program.
FrequentFlyerNumber string - The passenger's identifier for the program.
Status string - The passenger's program status.
StatusExpirationDate dateTime YYYY-MM-DDThh:mm:ss The expiration date for the passenger's program status.

Rail Program Element

Name Type Format Description
Description string - The description of the discount program.
DiscountProgramExpirationDate dateTime YYYY-MM-DDThh:mm:ss The date the discount program enrollment expires.
DiscountProgramType string - The type of the discount program.
ProgramNumber string - The passenger's identifier for the program.
Status string - The passenger's program status.
StatusExpirationDate dateTime YYYY-MM-DDThh:mm:ss The expiration date for the passenger's program status.

Rail Seat Element

Name Type Format Description
Amenities string - The amenities for the seat.
BerthPosition string - The berth location of the seat.
Deck string - Which deck the seat is on.
FacingForward string - Whether the seat is facing forward.
FareSpaceComfort string - The space around the seat.
PassengerRph integer - Which passenger the seat is assigned to.
SeatNumber string - The number of the seat.
SeatPosition string - The location of the seat.
SeatType string - The type of the seat.
SpaceType string - The type of space around the seat.
Status string - The status of the seat booking.
WagonNumber string - The number of the wagon the seat is on.
WagonType string - The type of wagon the seat is on.

Rule Violation Element

Name Type Format Description
CompanyReasonCode string - Internal Only. The reason code congifured by the Travel Admin to identify the violation of policy for the booked trip
CompanyRuleText string - Internal Only. The rule text configured by the Travel Admin.
ViolationReasonCode integer - Internal Only. The integer identifier for the reason code selected when the user violates the rules/policy configured by the Travel Admin.

Segment Option Item Element

Name Type Format Description
Flight array Segment Option Flight Type Element The flight options.
SegmentIndex string - The index of the segment among the options.
StatusCode string - The status of the segment option.
TimeStamp string - The timestamp for the segment option.

Segment Option Flight Type Element

Name Type Format Description
ArrAirp string - Arrival airport.
Cabin string - Cabin for the flight.
Carrier string - The flight carrier.
DepAirp string - Departure airport.
FlightNum string - The flight number.

Tax Element

Name Type Format Description
TaxAmount decimal - The amount of the tax.
TaxAuthority string - The entity levying the tax
TaxName string - The name of the tax.
TaxRate decimal - The tax percentage rate.
TaxType string - The type of the tax.

Error Schema

Errors Element

Name Type Format Description
errors array Error Element -

Error Element

Name Type Format Description
errorCode string - Code for the error.
errorMessage string - Message for the error.
errors array Error Element List of sub errors.

Booking

The Booking resource represents booking segments in the SAP Concur Travel system. TripLink suppliers use this resource to display a subset of the full booking fields.

Version

Version 1.1

URI

/travel/booking/v1.1/{query_parameters}

Scope

In order to obtain itinerary data when making Itinerary API calls, the value of the OAuth scope parameter must be set to: ITINER

Create or Update Booking

Creates a new booking or updates an existing booking. A new booking will be assigned to the specified trip, or if no trip is specified, the first itinerary that spans the booking dates. If no trip is specified and no itinerary exists that spans the booking dates, a new itinerary will be created.

This endpoint can be used to create/update bookings for a user that is not the OAuth consumer. This is most often done when a travel supplier or Travel Management Company needs to create/update a booking on behalf of a user. The supplier or TMC must be registered with SAP Concur, and must have an account that has one of the following user roles: Web Services Administrator for Professional, or Can Administer for Standard.

Request

POST /api/travel/booking/v1.0?tripId=12345678 HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}

Request Parameters

Query Parameters - Optional

Examples:

https://www.concursolutions.com/api/travel/booking/v1.1?tripId={tripId}

https://www.concursolutions.com/api/travel/booking/v1.1?userid_type=login_id&userid_value={loginID}

Content Type

application/xml

Authorization Header

Authorization header with OAuth token for a valid SAP Concur user. In order to create or update booking for anyone other than the OAuth consumer, the OAuth consumer must have one of the following user roles in SAP Concur: Company Administrator or Web Services Administrator for Professional, or Can Administer for Standard.

Create or Update Booking Request Schema

The request contains a Booking parent element with the following child elements:

Required Element Description
BookingSource The supplier's name.
RecordLocator Record locator for this booking. This is often six alphanumeric characters but can have other formats depending on the booking source
Optional Element Description
DateBookedLocal The date the booking was created, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss
FormOfPaymentName The name of the form of payment for the booking.
FormOfPaymentType The type of the form of payment.
TicketMailingAddress The mailing address for the booked ticket, if available.
TicketPickupLocation The pickup location for the booked ticket, if available.
TicketPickupNumber The confirmation number to pick up the booked ticket, if available.
AirfareQuotes List of stored airfare quotes for this booking.
AirlineTickets List of Airline Tickets for this booking.
Charges List of Charges for this booking.
MiscChargeOrders List of Miscellaneous AirCharges for this booking.
Passengers The Passengers element contains a Passenger child element for each booked passenger. The description of each child element can be seen in a subsequent table.
PassPrograms List of Pass Programs for this booking.
PhoneNumbers List of Phone numbers associated with this booking.
RailPayments List of Rail payments associated with rail segments in this booking.
Segments List of Segments in this booking. This parent element contains one or more Air, Car, Hotel, Dining, Ride, Rail, Parking, or Event parent elements for the booking. Refer to Booking Object Elements for more information about the child elements contained in the booking elements.
Delivery The method this booking was delivered. 
WaitListSegments The segments that the traveler is waitlisted for this booking.
Warnings The warnings associated with the booking.
WebAddresses List of web addresses such as emails, pickup URLs, etc. associated with this bookings

Passenger Child Elements

Required Element Description
NameFirst The first name of the passenger.
NameLast The last name of the passenger.
Optional Element Description
NameMiddle The middle name of the passenger.
NamePrefix The name prefix of the passenger.
NameRemark Additional details about the passenger's name.
NameSuffix The name suffix of the passenger.
NameTitle The title of the passenger.
TextName The user's full name as entered in the booking tool if different from the name in the database.
FrequentTravelerProgram Passenger's loyalty programs

Response

This function returns the full trip details, as documented in the Response of the Get Itinerary Details function.

If the end user updates an existing reservation which results in a new confirmation number, the old booking must be explicitly cancelled in addition to posting the new booking to SAP Concur. If the previous booking is not cancelled, the user will see both bookings in their SAP Concur trip list.

Examples

Example 1: XML Example Request

POST /api/travel/booking/v1.0?tripId=12345678 HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
...
<Booking xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <Segments>
        <Car>
            <Vendor>AL</Vendor>
            <VendorName>Alamo</VendorName>
            <Status>HK</Status>
            <StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
            <EndDateLocal>2013-12-23T12:00:00</EndDateLocal>
            <StartDateUtc>2013-12-21T20:00:00</StartDateUtc>
            <EndDateUtc>2013-12-23T20:00:00</EndDateUtc>
            <ConfirmationNumber>F16726AIUS</ConfirmationNumber>
            <DateCreatedUtc>2012-07-22T11:55:42</DateCreatedUtc>
            <DateModifiedUtc>2012-07-22T11:55:42</DateModifiedUtc>
            <StartCityCode>SEA</StartCityCode>
            <EndCityCode>SEA</EndCityCode>
            <StartLocation>SEA</StartLocation>
            <EndLocation>SEA</EndLocation>
            <Class>E</Class>
            <Body>C</Body>
            <Transmission>A</Transmission>
            <AirCondition>R</AirCondition>
            <NumPersons>1</NumPersons>
            <NumCars>1</NumCars>
            <DiscountCode>4321</DiscountCode>
            <DailyRate>35.0000</DailyRate>
            <TotalRate>105.0000</TotalRate>
            <RateType>D</RateType>
            <Currency>USD</Currency>
        </Car>
    </Segments>
    <RecordLocator>PANAMA50</RecordLocator>
    <BookingSource>Alamo</BookingSource>
    <DateCreatedUtc>2012-07-22T11:55:42</DateCreatedUtc>
    <DateModifiedUtc>2012-07-22T11:55:42</DateModifiedUtc>
    <DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
    <Passengers>
        <Passenger>
            <PassengerKey>0</PassengerKey>
            <NameFirst>Chris</NameFirst>
            <NameLast>Miller</NameLast>
        </Passenger>
    </Passengers>
</Booking>

Example 2: XML Example of Successful Response

<Itinerary xmlns="https://www.concursolutions.com/api/travel/trip/2010/06">
    <id>https://www.concursolutions.com/api/travel/trip/v1.1/CNQR1234567890</id>
    <ItinLocator>CNQR1234567890</ItinLocator>
    <ClientLocator>KK-CNQ-1M1P6-5HJ</ClientLocator>
    <ItinSourceName>TravelSupplier</ItinSourceName>
    <TripName>Trip to Seattle</TripName>
    <Comments />
    <StartDateLocal>2013-12-21T07:25:00</StartDateLocal>
    <EndDateLocal>2013-12-23T23:59:00</EndDateLocal>
    <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
    <BookedVia>EveryGDS</BookedVia>
    <BookedByFirstName>Chris</BookedByFirstName>
    <BookedByLastName>Miller</BookedByLastName>
    <DateBookedLocal>2012-07-24T19:15:52</DateBookedLocal>
    <Booking>
        <Segments>
            <Car>
                <Vendor>AL</Vendor>
                <VendorName>Alamo</VendorName>
                <Status>HK</Status>
                <StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
                <EndDateLocal>2013-12-23T12:00:00</EndDateLocal>
                <StartDateUtc>2013-12-21T20:00:00</StartDateUtc>
                <EndDateUtc>2013-12-23T20:00:00</EndDateUtc>
                <ConfirmationNumber>F16726AIUS</ConfirmationNumber>
                <DateCreatedUtc>2012-07-22T11:55:42</DateCreatedUtc>
                <DateModifiedUtc>2012-07-22T11:55:42</DateModifiedUtc>
                <StartCityCode>SEA</StartCityCode>
                <EndCityCode>SEA</EndCityCode>
                <StartLocation>SEA</StartLocation>
                <EndLocation>SEA</EndLocation>
                <Class>E</Class>
                <Body>C</Body>
                <Transmission>A</Transmission>
                <AirCondition>R</AirCondition>
                <NumPersons>1</NumPersons>
                <NumCars>1</NumCars>
                <DiscountCode>4321</DiscountCode>
                <DailyRate>35.0000</DailyRate>
                <TotalRate>105.0000</TotalRate>
                <RateType>D</RateType>
                <Currency>USD</Currency>
            </Car>
        </Segments>
        <RecordLocator>PANAMA50</RecordLocator>
        <BookingSource>Alamo</BookingSource>
        <DateCreatedUtc>2012-07-22T11:55:42</DateCreatedUtc>
        <DateModifiedUtc>2012-07-22T11:55:42</DateModifiedUtc>
        <DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
        <ItinSourceName>TravelSupplier</ItinSourceName>
        <Passengers>
            <Passenger>
                <PassengerKey>0</PassengerKey>
                <NameFirst>Chris</NameFirst>
                <NameLast>Miller</NameLast>
            </Passenger>
        </Passengers>
    </Booking>
</Itinerary>

Cancel a Booking

Cancels an existing booking. By default, the OAuth consumer should be the owner of the booking. This endpoint can also be used to cancel bookings that the OAuth consumer does not own. This is most often done when a Travel Management Company needs to cancel bookings on behalf of a user. The TMC must be registered with SAP Concur and have a SAP Concur account that has one of the following user roles: Web Services Administrator for Professional, or Can Administer for Standard.

NOTE:

Example:

https://{baseUri}/api/travel/booking/v1.1/cancel?bookingSource={Supplier}&confirmationNumber={confnum}

Request

POST /api/travel/booking/v1.1/cancel?bookingSource={FastTravel}&confirmationNumber={098765431} HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}

Request Parameters

Query Parameters - Required

The cancel keyword and the unique identifier for the supplier, configured by SAP Concur during the application review. The bookingSource must match the Supplier Name associated with the booking.

The confirmation number for the booking to cancel.

Example: https://www.concursolutions.com/api/travel/booking/v1.1/cancel?bookingSource={Supplier}&confirmationNumber={confnum}

Query Parameters - Optional

The SAP Concur login ID of the user who owns the booking. Only provided when the booking owner is not the OAuth consumer. Can only be used when the OAuth consumer has the required user role.

Example: https://www.concursolutions.com/api/travel/booking/v1.1/cancel?bookingSource={Supplier}&confirmationNumber={confnum}&userid_type=login_id&userid_value={loginID}

Content Type

application/xml

Authorization Header

The authorization header must have an OAuth token for valid SAP Concur user. The OAuth consumer must be registered as a Supplier or TMC with SAP Concur, and must have one of the following user roles in SAP Concur: Company Administrator or Web Services Administrator for Professional, or Can Administer for Standard.

Response

This function returns the full booking details, as specified in the Booking Object Elements section.

If the booking is not found, the function returns a HTTP 404 error and the following element:

Status: This element contains the value: NotFound.

Examples

Examples 1: XML Example Request

POST /api/travel/booking/v1.1/cancel?bookingSource={FastTravel}&confirmationNumber={098765431} HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}

Examples 2: XML Example of Successful Response

<Car>
    <Vendor>ZE</Vendor>
    <Status>HK</Status>
    <StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
    <EndDateLocal>2013-12-24T12:00:00</EndDateLocal>
    <TimeZoneId xsi:nil="true"/>
    <StartDateUtc>2013-12-21T20:00:00</StartDateUtc>
    <EndDateUtc>2013-12-24T20:00:00</EndDateUtc>
    <ConfirmationNumber>0987654321</ConfirmationNumber>
    <CancellationNumber>1029384756</CancellationNumber>
    <DateCreatedUtc>2012-07-22T11:55:42</DateCreatedUtc>
    <DateCancelledUtc>2012-07-25T14:21:35</DateCancelledUtc>
    <DateModifiedUtc>2012-07-22T11:55:42</DateModifiedUtc>
    <UpgradedDateTime xsi:nil="true"/>
    <IsUpgradeAllowed xsi:nil="true"/>
    <FrequentTravelerId/>
    <StartCityCode>SEA</StartCityCode>
    <EndCityCode>SEA</EndCityCode>
    <StartLocation>SEA</StartLocation>
    <EndLocation>SEA</EndLocation>
    <Class>E</Class>
    <Body>C</Body>
    <Transmission>M</Transmission>
    <AirCondition>R</AirCondition>
    <PhoneNumber/>
    <NumPersons xsi:nil="true"/>
    <NumCars>1</NumCars>
    <DiscountCode>346660</DiscountCode>
    <Charges>
        <Fixed>
            <Description>Dropoff Fee</Description>
            <Currency>USD</Currency>
            <Amount>0.0000</Amount>
            <StartDateLocal xsi:nil="true"/>
            <IsPaid xsi:nil="true"/>
            <SemanticsCode>DROPOFFFEE</SemanticsCode>
            <SemanticsVendorType>C</SemanticsVendorType>
        </Fixed>
        <RateWithAllowance>
            <Currency>USD</Currency>
            <Amount>44.0000</Amount>
            <StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
            <IsPaid xsi:nil="true"/>
            <SemanticsCode>DAYS</SemanticsCode>
            <SemanticsVendorType>C</SemanticsVendorType>
            <PerUnit>DAY</PerUnit>
            <NumUnits>1.0000</NumUnits>
            <AllowanceUnit/>
            <AllowanceNumUnits>250.0000</AllowanceNumUnits>
            <AllowanceAmount>0.2400</AllowanceAmount>
            <AllowanceIsUnlimited>false</AllowanceIsUnlimited>
        </RateWithAllowance>
    </Charges>
    <Remarks/>
    <PerDiemLocation/>
</Car>

See Also

Trip resource

Trips

The Trips resource represents itineraries in the Concur Travel system. TripLink suppliers use this resource to display a subset of the full booking fields.

Version

1.1

URI

/travel/trip/v1.1/{query_parameters}

Scope

In order to obtain itinerary data when making Itinerary API calls, the value of the OAuth scope parameter must be set to: ITINER

Operations

Get Trip Summaries

The Get Itinerary Summaries endpoint is used for retrieving trip summaries for the traveler whose account is associated with the OAuth access token used to make the API call. This endpoint can also be used to get trip summaries for a different user or the whole company. This is usually done when a Travel Management Company (TMC) needs to get trip summaries on behalf of a user or company.

Best Practices

Request

GET /travel/trip/v1.1/{query_parameters}

Query Parameters

All query parameters are optional.

To identify a specific user by login ID or XMLSyncID, you can specify the following request parameters:

Parameter Name Parameter Type Data Type Description
startDate date dateTime The URL-encoded start date (in Coordinated Universal Time, or UTC) for the trip. Format: YYYY-MM-DD. If no query parameters are provided, the start date is set to today's date - 30 days. The request will only return trips that are ongoing during the provided dates, either starting on the date, or starting before the date and ongoing during the provided date.
endDate date dateTime The URL-encoded UTC end date for the trip. Format: YYYY-MM-DD. If no query parameters are provided, the end date is set to today's date + 12 months. The request will only return trips that are ongoing during the provided dates, either ending on the date, or starting before the date and ongoing during the provided date.
createdAfterDate date dateTime The URL-encoded UTC date for when the trip was created. The query string will return trips created on or after this date. Used with the createdBeforeDate for finding trips created during a date range. Format: YYYY-MM-DD.
createdBeforeDate date dateTime The URL-encoded UTC date for when the trip was created. The query string will return trips created on or before this date. Used with the createdAfterDate for finding trips created during a date range. Format: YYYY-MM-DD.
lastModifiedDate date dateTime The last modified UTC date of the trips and their associated bookings. This query string will return only the trips where the trip or any of its associated bookings have a last modified date that is greater or equal to the supplied time. The provided date/time can be anytime between now and the first date of trip creation in the database. The format is either the date or the date and time combined.
bookingType type string The trip includes at least one booking of this type. Format: Air, Car, Dining, Hotel, Parking, Rail, or Ride.
userid_type=login userid string The loginID is the user's SAP Concur login ID. This parameter can only be used if the OAuth consumer has one of the user roles listed above.
userid_value userid string The userid_value of ALL can be sent to get trip summaries for all users at the company. This parameter can only be used if the OAuth consumer has one of the user roles listed above.
includeMetadata true/false string The includeMetadata query parameter combined with the ItemsPerPage and Page query parameters cause the response to be divided into pages. The response is wrapped in a ConcurResponse parent element, with both the response details and the paging metadata included. If the ItemsPerPage query parameter is not sent, the response will default to 200 if the Page query parameter is sent, or 1000 if the Page query parameter is not set. If the Page query parameter is not sent, the response will default to page 1.
ItemsPerPage number integer The includeMetadata query parameter combined with the ItemsPerPage and Page query parameters will cause the response to be divided into pages. The response will be wrapped in a ConcurResponse parent element, with both the response details and the paging metadata included. If the ItemsPerPage query parameter is not sent, the response will default to 200 if the Page query parameter is sent, or 1000 if the Page query parameter is not set. If the Page query parameter is not sent, the response will default to page 1.
includeVirtualTrip flag integer Virtual trips are segments booked offline through the Concur Request product. Set the includeVirtualTrip query parameter to 1 to include those trips in the list.
includeCanceledTrips true/false string The includeCanceledTrips query parameter will cause the request to also return trips with a status of Canceled. When this query parameter is set to true, the response will include the TripStatus element.
includeGuestBookings true/false string The includeGuestBookings query parameter will cause the request to show guest bookings if set to true. It is set to false by default.

Here are some examples of how to format GET requests using a combination of these query parameters:

https://www.concursolutions.com/api/travel/trip/v1.1/?startDate={_startdate_}&endDate={_enddate_}_&_createdAfterDate={_date_}&createdBeforeDate={_date_}&lastModifiedDate={_date_}&bookingType={_type_}&userid_type=login&userid_value=ALL

The access token used to make the API call must be associated with an account that has the Admin user role.

https://www.concursolutions.com/api/travel/trip/v1.1/?startDate={_startdate_}&endDate={_enddate_}_&_createdAfterDate={_date_}&createdBeforeDate={_date_}&lastModifiedDate={_date_}&bookingType={_type_}

The access token used to make the API call is associated with the account for the app making the call.

https://www.concursolutions.com/api/travel/trip/v1.1/?startDate={_startdate_}&endDate={_enddate_}_&_createdAfterDate={_date_}&createdBeforeDate={_date_}&lastModifiedDate={_date_}&bookingType={_type_}&userid_type=login_id&userid_value={_loginID_}

The access token used to make the API call is associated with the SAP Concur account with the specified login credentials.

Headers

Authorization Header (Required)

Authorization: OAuth {access_token} Where access_token is the OAuth 2.0 access token of the user whose itinerary information you want to retrieve. If you want to access company-wide itinerary information, the SAP Concur user account associated with the OAuth 2.0 access token must have one of these roles: Web Services Administrator for Professional or Can Administer for Standard.

Accept Header (optional)

application/xml

Get Trip Summaries Response Schema

The response returns an ItineraryInfoList parent element with an ItineraryInfo child element for each trip summary for the specified traveler. If the includeMetadata and ItemsPerPage query parameters are included in the request, the response will include a ConnectResponse parent element which contains a MetaData element with paging information and a Data element with an ItineraryInfoList child element. The response for this operation can be divided into pages for easier processing.

Data Elements

Element Name Data Type Description
ItineraryInfoList element Parent element with an ItineraryInfo child element for each trip summary for the specified traveler.

ItineraryInfoList Elements

Element Name Data Type Description
ItineraryInfo element Parent element with the information about an itinerary for the specified user.

ItineraryInfo Elements

Element Name Data Type Description
TripId string Encrypted trip identifier value.
TripName string Name of the trip.
TripStatus string The status of the trip. This element only appears if the includeCanceledTrips query parameter is used in the request.
StartDateLocal dateTime The start date of the trip in the starting location’s timezone. Format: YYYY-MM-DDThh:mm:ss.
EndDateLocal dateTime The end date of the trip in the ending location’s timezone. Format: YYYY-MM-DDThh:mm:ss.
DateModifiedUtc dateTime The UTC date that this trip was last modified. Format: YYYY-MM-DDThh:mm:ss.
UserLoginId string The user's login to SAP Concur. This element appears in the response of the GET /api/travel/trip/v1.1 operation when the OAuth 2.0 is access token is associated with an SAP Concur account with one of these roles: Web Services Administrator for Professional or Can Administer for Standard.
id string Trip ID URI with encrypted ID.

Metadata Element

The parent element of the paging information.

Paging Elements

Element Name Data Type Description
TotalPages integer The total number of pages the query returned.
TotalItems integer The total number of itineraries the query returned.
CurrentPage integer The page number for the set of results in the current response.
ItemsPerPage integer The number of items set to display per page.
PreviousPageURL string The URI to the previous page of results. This element will be empty when there are no previous pages.
NextPageURL string The URI to the next set of results. This element will be empty when there are no next pages.

Examples

Example 1: Get Trip Summaries by Start and End Date

Request

GET /api/travel/trip/v1.1/?startDate=2012%2F02%2F01&endDate=2013%2F12%2F31 HTTP/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
...

Response

HTTP/1.1 200 OK
Content-Type: application/xml
...

<?xml version="1.0" encoding="utf-8"?>
<ItineraryInfoList xmlns="http://www.concursolutions.com/api/travel/trip/2010/06" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <ItineraryInfo>
        <TripId>naIzQJ0y2DBWjCIQOb2SHTsozwBsHDkdP</TripId>
        <TripName>Trip from Baltimore to New York</TripName>
        <StartDateLocal>2012-02-15T09:00:00</StartDateLocal>
        <EndDateLocal>2012-02-21T17:30:00</EndDateLocal>
        <UserLoginId>cm@example.com</UserLoginId>
        <DateModifiedUtc>2012-02-14T17:13:07</DateModifiedUtc>
        <id>https://www.concursolutions.com/api/travel/trip/v1.1/naIzQJ0y2DBWjCIQOb2SHTsozwBsHDkdP</id>
    </ItineraryInfo>
    <ItineraryInfo>
        <TripId>I2uwiJJw8r7Owl3IWlSie9WIelxhAhwiL</TripId>
        <TripName>Trip from Baltimore to Seattle</TripName>
        <StartDateLocal>2012-03-26T09:00:00</StartDateLocal>
        <EndDateLocal>2012-03-29T17:30:00</EndDateLocal>
        <DateModifiedUtc>2012-03-24T19:00:00</DateModifiedUtc>
        <UserLoginId>cm@example.com</UserLoginId>
        <id>https://www.concursolutions.com/api/travel/trip/v1.1/I2uwiJJw8r7Owl3IWlSie9WIelxhAhwiL</id>
    </ItineraryInfo>
</ItineraryInfoList>

Example 2: Get Trip Summary by Booking Type and Start Date Request

This request returns trip summaries for trips that started by the specified date for the specified booking type.

Request

GET /api/travel/trip/v1.1/?startDate=2015%2F01%2F01&bookingType=Air HTTP/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
...

Response

HTTP/1.1 200 OK
Content-Type: application/xml
...

<?xml version="1.0" encoding="utf-8"?>
<ItineraryInfoList xmlns="http://www.concursolutions.com/api/travel/trip/2010/06" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <ItineraryInfo>
        <TripId>I2uwiJJw8r7OwCIQOb2SHTsozwBsSie9W</TripId>
        <TripName>Trip by air from Seattle to San Francisco</TripName>
        <StartDateLocal>2015-01-01T12:30:00</StartDateLocal>
        <EndDateLocal>2015-01-05T10:30:00</EndDateLocal>
        <UserLoginId>cm@example.com</UserLoginId>
        <DateModifiedUtc>2014-12-23T11:10:00</DateModifiedUtc>
        <id>https://www.concursolutions.com/api/travel/trip/
        v1.1/I2uwiJJw8r7OwCIQOb2SHTsozwBsSie9W</id>
    </ItineraryInfo>
</ItineraryInfoList>

Example 3: Get Trip Summary by Created Date

This requests returns trip summaries created after the specified date.

Request

GET /api/travel/trip/v1.1/?createdAfterDate=2015%2F02%2F13 HTTP/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}

Response

HTTP/1.1 200 OK
Content-Type: application/xml
...

<?xml version="1.0" encoding="utf-8"?>
<ItineraryInfoList xmlns="http://www.concursolutions.com/api/travel/trip/2010/06" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <ItineraryInfo>
        <TripId>BWjCIJJw8r7OwCIQOb2SHTsozwBsWlSie9</TripId>
        <TripName>Trip by air from Los Angeles to Mexico City</TripName>
        <StartDateLocal>2015-03-09T18:45:00</StartDateLocal>
        <EndDateLocal>2015-03-30T08:00:00</EndDateLocal>
        <UserLoginId>cm@example.com</UserLoginId>
        <DateModifiedUtc>2015-01-28T09:30:00</DateModifiedUtc>
        <id>https://www.concursolutions.com/api/travel/trip/
        v1.1/BWjCIJJw8r7OwCIQOb2SHTsozwBsWlSie9</id>
    </ItineraryInfo>
</ItineraryInfoList>

Example 4: Get Trip Summary with Paging

This request is used for dividing the response into pages for easier processing.

Request

GET /api/travel/trip/v1.1/?createdAfterDate=2012%2F02%2F01&includeMetadata=true&ItemsPerPage=2&Page=1 HTTP/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}

Response

The response returns a ConnectResponse parent element which contains a MetaData element with paging information and a Data element with an ItineraryInfoList child element.

HTTP/1.1 200 OK
Content-Type: application/xml
...

<ConnectResponse>
    <Metadata>
        <Paging>
            <TotalPages>38</TotalPages>
            <TotalItems>187</TotalItems>
            <CurrentPage>2</CurrentPage>
            <ItemsPerPage>2</ItemsPerPage>
            <PreviousPageURL>https://www.concursolutions.com/api/travel/trip/v1.1/?
                createdAfterDate=2012%2F02%2F01&amp;
                itemsPerPage=5&amp;page=3&amp;includeMetaData=true</PreviousPageURL>
            <NextPageURL>https://www.concursolutions.com/api/travel/trip/v1.1/?
                createdAfterDate=2012%2F02%2F01&amp;
                itemsPerPage=5&amp;page=1&amp;includeMetaData=true</NextPageURL>
        </Paging>
    </Metadata>
    <Data>
        <ItineraryInfoList xmlns="http://www.concursolutions.com/api/travel/trip/2010/06" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
            <ItineraryInfo>
                <TripId>naIzQJ0y2DBWjCIQOb2SHTsozwBsHDkdP</TripId>
                <TripName>Trip from Baltimore to New York</TripName>
                <StartDateLocal>2012-02-15T09:00:00</StartDateLocal>
                <EndDateLocal>2012-02-21T17:30:00</EndDateLocal>
                <UserLoginId>cm@example.com</UserLoginId>
                <DateModifiedUtc>2012-02-14T17:13:07</DateModifiedUtc>
                <id>https://www.concursolutions.com/api/travel/trip/v1.1/naIzQJ0y2DBWjCIQOb2SHTsozwBsHDkdP</id>
            </ItineraryInfo>
            <ItineraryInfo>
                <TripId>I2uwiJJw8r7Owl3IWlSie9WIelxhAhwiL</TripId>
                <TripName>Trip from Baltimore to Seattle</TripName>
                <StartDateLocal>2012-03-26T09:00:00</StartDateLocal>
                <EndDateLocal>2012-03-29T17:30:00</EndDateLocal>
                <DateModifiedUtc>2012-03-24T19:00:00</DateModifiedUtc>
                <UserLoginId>cm@example.com</UserLoginId>
                <id>https://www.concursolutions.com/api/travel/trip/v1.1/I2uwiJJw8r7Owl3IWlSie9WIelxhAhwiL</id>
            </ItineraryInfo>
        </ItineraryInfoList>
    </Data>
</ConnectResponse>

Get Trip Details

The Get Itinerary Details endpoint is used for getting details for the specified trip. The elements included in the response vary as follows:

This topic describes the full set of possible elements that can be returned. No itinerary can contain all of the possible elements, so the response will always be a subset of all the possible returned values.

By default, when calling this API, the SAP Concur account associated with the OAuth access token used to make the API call should be the owner of the trip. This endpoint can also be used to get details for trips that the OAuth consumer does not own. This is most often done when a TMC needs to get trip details on behalf of a user. The TMC must be registered with SAP Concur and have an SAP Concur account that has one of the following user roles: Web Services Administrator for Professional, or Can Administer for Standard.

Request

GET /travel/trip/v1.1/trip_ID?[systemFormat=system_format|&userid_type=login|&user_id=login_ID]

Path Parameters

Parameter Name Data Type Description
trip_ID string Required: The identifier for the desired trip. This identifier is returned as the value of the ID element when getting trip summaries. For example, if the returned value of the ID element is I2uwiJJw8r7Owl3IWlSie9WIelxhAhwiL, then the URI for the request is /travel/trip/v1.1/I2uwiJJw8r7Owl3IWlSie9WIelxhAhwi.

Query Parameters

Parameter Name Data Type Description
systemFormat string Optional: Format of the response for a different system. The supported value is Tripit. The format for the request URI using this query parameter is /travel/trip/v1.1/trip_ID?systemFormat=Tripit.
userid_type string Optional: The type of user identification to use. Possible value is: login.
userid_value string Optional: The user's login ID. This parameter must be provided in conjunction with the userid_type parameter. The userid_type and userid_value parameters can only be used if the user account associated with the OAuth 2.0 access token must have an SAP Concur account with one of these roles: Web Services Administrator for Professional or Can Administer for Standard. The format for the request URI using the userid_type and userid_value query parameters is /travel/trip/v1.1/trip_ID?userid_type=login&userid_value=login_ID.

Headers

Authorization Header (Required)

Authorization: OAuth {access_token}
Where access_token is the OAuth 2.0 access token of the user whose itinerary information you want to retrieve. If you want to access company-wide itinerary information, the user account associated with the OAuth 2.0 access token must have an SAP Concur account with one of these roles: Web Services Administrator for Professional or Can Administer for Standard.

Accept Header (Optional)

application/xml

Get Trip Details Response Schema

The response returns subset of the elements described in the following tables depending on the parameters used in the request and the status and details for the itinerary. The response can be formatted for TripIt, using the systemformat query string.

Parent Elements

Element Name Data Type Description
id string Trip ID URI with encrypted ID.
ItinLocator string The itinerary locator. This element is now deprecated and only supported for backward compatibility.
ClientLocator string Represents the unique identifier of the trip in an external (non-Concur) system. Maximum length 32 characters.
ItinSourceName string The itinerary source. Format: TravelSupplier.
TripName string Name of the trip. Maximum length 255 characters.
Comments string Comments for this itinerary. Maximum length 512 characters.
StartDateLocal dateTime The start date of the trip in the starting location’s timezone. Format: YYYY-MM-DDThh:mm:ss.
EndDateLocal dateTime The end date of the trip in the ending location’s timezone. Format: YYYY-MM-DDThh:mm:ss.
DateCreatedUtc dateTime The date that this trip was created, in UTC. Format: YYYY-MM-DDThh:mm:ss.
DateModifiedUtc dateTime The UTC date that this trip was last modified. Format: YYYY-MM-DDThh:mm:ss.
BookedVia string The booking method for the trip.
BookedByFirstName string The first name of the person who booked the trip.
BookedByLastName string The last name of the person who booked the trip.
DateBookedLocal dateTime The date the trip was booked, in the local time of the booking location. Format: YYYY-MM-DDThh:mm:ss.
CancelComments string The comments provided if the itinerary is cancelled. Maximum length: 256 characters.
Description string The trip description. Maximum length: 512 characters.
EndDateUtc dateTime The end date of the trip, in UTC. Format: YYYY-MM-DDThh:mm:ss.
IsPersonal boolean Whether the trip is a Business or Leisure trip. Format: true/false.
ProjectName string The associated project name for the trip. Maximum length: 255 characters.
StartDateUtc dateTime The start date of the trip, in UTC. Format: YYYY-MM-DDThh:mm:ss.
RuleViolations array The list of rule violations associated with the itinerary. This parent element contains a RuleViolation child element for each associated rule violation.
Status string The status of the itinerary. One of the following: 0- Confirmed; 1- Ticketed by agent; 2- Canceled.
Bookings array A parent element that contains a Booking child element for each booking associated with this itinerary.

Booking Element

Element Name Data Type Description
Segments array List of segments in this booking. The child elements included in this element vary depending on whether a TMC, SAP Concur client, third-party developer, or TripLink supplier is requesting the itinerary details: For TMCs, clients, and third-party developers, the Segments element contains one or more Air, Car, Hotel, Dining, Ride, Rail, Parking, or Travel parent elements. For TripLink suppliers, the Segments element contains one or more Air, Car, Hotel, or Ride parent elements.
Passengers array Contains a Passenger child element for each included passenger. For more information on the Passengers element, see Create a New Trip.
RecordLocator string The unique identifier for a booking. This is often six alphanumeric characters, but can have other formats depending on the booking source.
BookingSource string The name of the booking source for this booking. A booking source is a textual name the system uses to track where a booking took place.
DateModifiedUtc dateTime The date the booking was last modified, in UTC. Format: YYYY-MM-DDThh:mm:ss.
DateBookedLocal dateTime The date the booking was created, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss.
ItinSourceName string The itinerary source. Format: TravelSupplier.
PassengerCount integer The number of passengers included in the booking.

Examples

Example 1: Get Trip Details for a Trip ID

Request

GET /api/travel/trip/v1.1/CNQR1234567890 HTTP/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
...

Response

HTTP/1.1 200 OK
Content-Type: application/xml
...

<?xml version="1.0" encoding="utf-8"?>
<Itinerary xmlns="http://www.concursolutions.com/api/travel/trip/2010/06">
    <id>https://www.concursolutions.com/api/travel/trip/v1.1/CNQR1234567890</id>
    <ItinLocator>CNQR1234567890</ItinLocator>
    <ClientLocator>KK-CNQ-1M1P6-5HJ</ClientLocator>
    <ItinSourceName>ConcurTravel</ItinSourceName>
    <TripName>Trip from Dallas to Seattle</TripName>
    <Comments />
    <StartDateLocal>2013-12-21T07:25:00</StartDateLocal>
    <EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
    <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
    <BookedVia>EveryGDS</BookedVia>
    <BookedByFirstName>Chris</BookedByFirstName>
    <BookedByLastName>Miller</BookedByLastName>
    <DateBookedLocal>2012-07-24T19:15:52</DateBookedLocal>
    <Bookings>
        <Booking>
            <Segments>
                <Car>
                    <Vendor>CQ</Vendor>
                    <Status>HK</Status>
                    <StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
                    <EndDateLocal>2013-12-24T12:00:00</EndDateLocal>
                    <ConfirmationNumber>F1672664579</ConfirmationNumber>
                    <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
                    <StartCityCode>SEA</StartCityCode>
                    <EndCityCode>SEA</EndCityCode>
                    <StartLocation>SEA</StartLocation>
                    <EndLocation>SEA</EndLocation>
                    <Class>E</Class>
                    <Body>C</Body>
                    <Transmission>M</Transmission>
                    <AirCondition>R</AirCondition>
                    <NumCars>1</NumCars>
                    <DiscountCode>346660</DiscountCode>
                    <DailyRate>44.0000</DailyRate>
                    <TotalRate>44.0000</TotalRate>
                    <RateType>D</RateType>
                    <Currency>USD</Currency>
                    <Charges>
                        <Fixed>
                            <Description>Dropoff Fee</Description>
                            <Currency>USD</Currency>
                            <Amount>0.0000</Amount>
                            <IsPrimary>false</IsPrimary>
                            <SemanticsCode>DROPOFFFEE</SemanticsCode>
                            <SemanticsVendorType>C</SemanticsVendorType>
                        </Fixed>
                        <RateWithAllowance>
                            <Currency>USD</Currency>
                            <Amount>44.0000</Amount>
                            <StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
                            <IsPrimary>true</IsPrimary>
                            <SemanticsCode>DAYS</SemanticsCode>
                            <SemanticsVendorType>C</SemanticsVendorType>
                            <PerUnit>DAY</PerUnit>
                            <NumUnits>1.0000</NumUnits>
                            <AllowanceNumUnits>250.0000</AllowanceNumUnits>
                            <AllowanceAmount>0.2400</AllowanceAmount>
                            <AllowanceIsUnlimited>false</AllowanceIsUnlimited>
                        </RateWithAllowance>
                    </Charges>
                </Car>
            </Segments>
            <Passengers>
                <Passenger>
                    <NameFirst>Chris</NameFirst>
                    <NameLast>Miller</NameLast>
                </Passenger>
            </Passengers>
            <RecordLocator>C123456789</RecordLocator>
            <BookingSource>ConcurCars</BookingSource>
            <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
            <DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
            <ItinSourceName>TravelSupplier</ItinSourceName>
            <PassengerCount>1</PassengerCount>
        </Booking>
        <Booking>
            <Segments>
                <Hotel>
                    <Vendor>CQ</Vendor>
                    <Status>GK</Status>
                    <StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
                    <EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
                    <ConfirmationNumber>3364214265</ConfirmationNumber>
                    <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
                    <RateCode>LV4</RateCode>
                    <Name>CONCUR HOTEL</Name>
                    <HotelPropertyId>CONQ</HotelPropertyId>
                    <CheckinTime>00:00</CheckinTime>
                    <CheckoutTime>00:00</CheckoutTime>
                    <NumPersons>1</NumPersons>
                    <NumRooms>1</NumRooms>
                    <CancellationPolicy>Cxl 1 day prior to Arrival</CancellationPolicy>
                    <DailyRate>240.3500</DailyRate>
                    <Currency>USD</Currency>
                    <RoomDescription>1 KING BED ACCESSIBLE ROOM - K1RRC</RoomDescription>
                    <Charges>
                        <Rate>
                            <Currency>USD</Currency>
                            <Amount>240.3500</Amount>
                            <StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
                            <IsPrimary>false</IsPrimary>
                            <SemanticsCode>ROOMRATE</SemanticsCode>
                            <SemanticsVendorType>H</SemanticsVendorType>
                            <PerUnit>DAY</PerUnit>
                            <NumUnits>3.0000</NumUnits>
                        </Rate>
                    </Charges>
                </Hotel>
            </Segments>
            <Passengers>
                <Passenger>
                    <NameFirst>Chris</NameFirst>
                    <NameLast>Miller</NameLast>
                </Passenger>
            </Passengers>
            <RecordLocator>0987654321</RecordLocator>
            <BookingSource>ConcurHotel</BookingSource>
            <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
            <DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
            <OriginalItinLocator>33491211</OriginalItinLocator>
            <ItinSourceName>ConcurTravel</ItinSourceName>
            <PassengerCount>1</PassengerCount>
        </Booking>
    </Bookings>
</Itinerary>

Example 2: Get Trip Details in TripIt Format

Request

GET /travel/trip/v1.1/73014481752?systemFormat=Tripit HTTP/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
...

Response

<?xml version="1.0" encoding="utf-8"?>
<Response>
    <Trip>
        <id>73014481752</id>
        <relative_url>/api/travel/trip/v1.1/73014481752</relative_url>
        <start_date>2013-08-21</start_date>
        <end_date>2013-08-24</end_date>
        <display_name>Strategy Team meeting</display_name>
        <is_private>true</is_private>
    </Trip>
    <AirObject>
        <booking_site_conf_num>RL10001005</booking_site_conf_num>
        <booking_site_name>Concur Travel</booking_site_name>
        <booking_site_phone></booking_site_phone>
        <booking_site_url>https://www.concursolutions.com</booking_site_url>
        <record_locator>4294993825</record_locator>
        <supplier_conf_num>CN10001005</supplier_conf_num>
        <supplier_contact></supplier_contact>
        <supplier_email_address></supplier_email_address>
        <supplier_name></supplier_name>
        <supplier_phone></supplier_phone>
        <supplier_url></supplier_url>
        <is_purchased>1</is_purchased>
        <notes></notes>
        <restrictions></restrictions>
        <total_cost></total_cost>
        <Segment>
            <StartDateTime>
                <date>2013-08-21</date>
                <time>07:45:00</time>
            </StartDateTime>
            <EndDateTime>
                <date>2013-08-21</date>
                <time>13:03:00</time>
            </EndDateTime>
            <start_airport_code>PHX</start_airport_code>
            <start_gate>A11</start_gate>
            <start_terminal>4</start_terminal>
            <end_airport_code>ORD</end_airport_code>
            <end_gate>F8</end_gate>
            <end_terminal>2</end_terminal>
            <marketing_airline>US</marketing_airline>
            <marketing_flight_number>1</marketing_flight_number>
            <aircraft>320</aircraft>
            <duration></duration>
            <distance>1433</distance>
            <notes></notes>
            <seats></seats>
            <service_class>Economy</service_class>
            <stops>Nonstop</stops>
        </Segment>
        <Segment>
            <StartDateTime>
                <date>2013-08-24</date>
                <time>13:55:00</time>
            </StartDateTime>
            <EndDateTime>
                <date>2013-08-24</date>
                <time>16:58:00</time>
            </EndDateTime>
            <start_airport_code>ORD</start_airport_code>
            <start_gate></start_gate>
            <start_terminal></start_terminal>
            <end_airport_code>PHX</end_airport_code>
            <end_gate></end_gate>
            <end_terminal></end_terminal>
            <marketing_airline>US</marketing_airline>
            <marketing_flight_number>1728</marketing_flight_number>
            <aircraft>A320</aircraft>
            <duration></duration>
            <distance></distance>
            <notes></notes>
            <seats></seats>
            <service_class>Economy</service_class>
            <stops> stops</stops>
        </Segment>
        <Traveler>
            <first_name>William</first_name>
            <middle_name></middle_name>
            <last_name>Never</last_name>
            <frequent_traveler_num></frequent_traveler_num>
            <frequent_traveler_supplier></frequent_traveler_supplier>
            <ticket_num></ticket_num>
        </Traveler>
    </AirObject>
</Response>  

Create a New Trip

This endpoint is used for creating a new trip. To create a new trip, the specified dates in the content body can only span the trip to be created and cannot span an existing trip. To create or update a trip on behalf of a user, the OAuth access token used to make the API call should be associated with the SAP Concur account of that user. The TripLink supplier or TMC must be registered with SAP Concur and have an SAP Concur account that has one of the following user roles: Web Services Administrator for Professional, or Can Administer for Standard.

Request

POST /travel/trip/v1.1?[userid_type=login&user_id=login_ID]

Request Parameters

Parameter Name Data Type Description
userid_type string Optional: The type of user identification to use. Possible value is: login_id.
userid_value string Optional: The value for the user identification type. Currently the only available type is login_id so the value is the login credentials. This parameter must be provided in conjunction with the userid_type parameter. The userid_type and userid_value parameters can only be used if the user account associated with the OAuth 2.0 access token is associated with an SAP Concur account with one of these roles: Web Services Administrator for Professional or Can Administer for Standard. The format for the request URI using the userid_type and userid_value query parameters is /travel/trip/v1.1/trip_ID?userid_type=login&userid_value=login_ID.

Headers

Authorization Header (required)

Authorization: OAuth {access_token}

Where access_token is the OAuth 2.0 access token of the user whose trip you want to create or update. If you want to access company-wide itinerary information, the user account associated with the OAuth 2.0 access token must have an SAP Concur account with one of these roles: Web Services Administrator for Professional or Can Administer for Standard.

Create New Trip Request Schema

Element Name Required or Optional TripLink Data Type Description
Itinerary required Y ItineraryType The root element for a trip. For this endpoint, it contains the following elements: ClientLocator, ItinSourceName, TripName, Comments, StartDateLocal, EndDateLocal, BookedByFirstName, BookedByLastName, Bookings.
TripName required Y string Name of the trip. Maximum length: 255 characters.
TripStatus required Y unsignedByte The status of the trip. One of the following: 0 - Confirmed; 1 - Ticketed; 2 - Canceled; 6 - Proposal; 7 - Booked Proposal. This element only appears if the includeCanceledTrips query parameter is used in the request.
RecordLocator required Y string The unique identifier for a booking. This is often six alphanumeric characters, but can have other formats depending on the booking source.
BookingSource required Y string The name of the booking source for this booking. A booking source is a textual name the system uses to track where a booking took place. This could be a GDS, OTA, Vendor code for a Supplier website, or Supplier Direct Connect API. For TripLink suppliers, this is the supplier's name.
StartDateLocal optional Y dateTime The start date of the trip in the starting location’s timezone. Format: YYYY-MM-DDThh:mm:ss.
EndDateLocal optional Y dateTime The end date of the trip in the ending location’s timezone. Format: YYYY-MM-DDThh:mm:ss.
BookedByFirstName optional Y string The first name of the person who booked the trip.
BookedByLastName optional Y string The last name of the person who booked the trip.
Bookings optional Y array A parent element that contains a Booking child element for each booking associated with this itinerary.
Booking optional Y array A child element of the Bookings element which in turn contains the following child elements: Segments, Passengers, RecordLocator, BookingSource, DateModifiedUtc, DateBookedLocal, ItinSourceName, and PassengerCount.
Segments optional Y array List of segments in this booking. The child elements included in this element vary depending on whether a TMC, client, third-party developer, or TripLink supplier is requesting the itinerary details: For TMCs, clients, and third-party developers, the Segments element contains one or more Air, Car, Hotel, Dining, Ride, Rail, Parking, or Travel parent elements. For TripLink suppliers, the Segments element contains one or more Air, Car, Hotel, or Ride parent elements.
Comments optional Y string Comments for the itinerary. Maximum length: 512 characters.
ItinSourceName optional N string The itinerary source. Format: TravelSupplier.
BookingOwner optional Y string Indicates the tool that supplied the booking to Concur Travel.
Source optional N/A string This element is obsolete. It is supported for backward compatibility only.
DateBookedLocal optional Y dateTime The date the booking was created, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss.
FormOfPaymentName optional - string The name of the form of payment for the booking.
FormOfPaymentType optional - string The type of the form of payment.
TicketMailingAddress optional - - The mailing address for the booked ticket, if available.
TicketPickupLocation optional - - The pickup location for the booked ticket, if available.
TicketPickupNumber optional - - The confirmation number for the booked ticket, if available.
AirfareQuotes optional - array List of stored airfare quotes for this booking.
Airline Tickets optional - array List of airline tickets for this booking.
Charges optional - array List of charges for this booking.
MiscChargeOrders optional - array List of miscellaneous air charges for this booking.
Passengers optional Y array Contains a Passenger child element for each included passenger. The Passenger child element in turn contains the following required child elements: NameFirst, NameLast, and the following optional elements: NameMiddle, NamePrefix, NameRemark, NameSuffix, NameTitle, TextName, and FrequentTravelerProgram.
PassPrograms optional - array List of pass programs for this booking. This parent element has a PassProgram child element for each pass program associated with the booking. The PassProgram parent element has the following child elements: Amount, Name, Type, UserFirstName, and UserLastname.
PhoneNumbers optional - array List of phone numbers associated with this booking. This parent element has a PhoneNumberData child element for each phone number associated with the booking. The PhoneNumberData parent element has the following child elements: PassengerRPH, PhoneNumber, Type, and Description.
RailPayments optional - array List of rail payments associated with rail segments in this booking. It has the following child elements: RailPayment that represents the payment information for a rail booking and RailAdjustment for the amount adjusted for a rail booking.
Segments optional Y array List of segments in this booking. The child elements included in this element vary depending on whether a TMC, client, third-party developer, or TripLink supplier is requesting the itinerary details: For TMCs, clients, and third-party developers, the Segments element contains one or more Air, Car, Hotel, Dining, Ride, Rail, Parking, or Travel parent elements. For TripLink suppliers, the Segments element contains one or more Air, Car, Hotel, or Ride parent elements.
Delivery optional - - The method this booking was delivered.
WaitListSegments optional - - The segments that the traveler is waitlisted for this booking.
Warning optional - - The warnings associated with the booking.
WebAddresses optional - - List of web addresses such as emails, pick-up URLs, and so on associated with this booking.

Create New Trip Response Schema

The response returns an HTTP status code and if the trip is created successfully, it also returns the full posted trip details with the following additional elements inside the Itinerary parent element:

Element Name Data Type TripLink Description
id string Y The URI including the trip ID.
ItinLocator string Y The Itinerary Locator value (trip ID without the URL). The ItinLocator value is used when updating an existing trip.
DateModifiedUtc dateTime Y The UTC formatted date that this booking was last modified.
BookedVia string Y The booking method or the GDS the itinerary was booked in.
DateBookedLocal dateTime Y The date, in the traveler’s local time, that the booking was made.

Examples

Example 1: TMC Creates a Trip for User Using Their Login Credentials

This example shows how to create a trip for a user using their login credentials.

Request

POST /api/travel/trip/v1.1?userid_type=login_id&userid_value=cm@example.com HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
Content-Type: application/xml
...

<Itinerary xmlns="http://www.concursolutions.com/api/travel/trip/2010/06">
    <ClientLocator>KK-CNQ-1M1P6-5HJ</ClientLocator>
    <ItinSourceName>ConcurConnectAPI</ItinSourceName>
    <TripName>Trip from Dallas to Seattle</TripName>
    <Comments />
    <StartDateLocal>2013-12-21T07:25:00</StartDateLocal>
    <EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
    <BookedByFirstName>Chris</BookedByFirstName>
    <BookedByLastName>Miller</BookedByLastName>
    <Bookings>
        <Booking>
            <Segments>
                <Car>
                    <Vendor>CQ</Vendor>
                    <Status>HK</Status>
                    <StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
                    <EndDateLocal>2013-12-24T12:00:00</EndDateLocal>
                    <ConfirmationNumber>F1672664579</ConfirmationNumber>
                    <StartCityCode>SEA</StartCityCode>
                    <EndCityCode>SEA</EndCityCode>
                    <StartLocation>SEA</StartLocation>
                    <EndLocation>SEA</EndLocation>
                    <Class>E</Class>
                    <Body>C</Body>
                    <Transmission>M</Transmission>
                    <AirCondition>R</AirCondition>
                    <NumCars>1</NumCars>
                    <DiscountCode>346660</DiscountCode>
                    <DailyRate>44.0000</DailyRate>
                    <TotalRate>44.0000</TotalRate>
                    <RateType>D</RateType>
                    <Currency>USD</Currency>
                    <Charges>
                        <Fixed>
                            <Description>Dropoff Fee</Description>
                            <Currency>USD</Currency>
                            <Amount>0.0000</Amount>
                            <IsPrimary>false</IsPrimary>
                            <SemanticsCode>DROPOFFFEE</SemanticsCode>
                            <SemanticsVendorType>C</SemanticsVendorType>
                        </Fixed>
                        <RateWithAllowance>
                            <Currency>USD</Currency>
                            <Amount>44.0000</Amount>
                            <StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
                            <IsPrimary>true</IsPrimary>
                            <SemanticsCode>DAYS</SemanticsCode>
                            <SemanticsVendorType>C</SemanticsVendorType>
                            <PerUnit>DAY</PerUnit>
                            <NumUnits>1.0000</NumUnits>
                            <AllowanceNumUnits>250.0000</AllowanceNumUnits>
                            <AllowanceAmount>0.2400</AllowanceAmount>
                            <AllowanceIsUnlimited>false</AllowanceIsUnlimited>
                        </RateWithAllowance>
                    </Charges>
                </Car>
            </Segments>
            <Passengers>
                <Passenger>
                    <NameFirst>Chris</NameFirst>
                    <NameLast>Miller</NameLast>
                </Passenger>
            </Passengers>
            <RecordLocator>C123456789</RecordLocator>
            <BookingSource>TravelBookings.com</BookingSource>
            <DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
            <ItinSourceName>ConcurConnectAPI</ItinSourceName>
            <PassengerCount>1</PassengerCount>
        </Booking>
        <Booking>
            <Segments>
                <Hotel>
                    <Vendor>CQ</Vendor>
                    <Status>GK</Status>
                    <StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
                    <EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
                    <ConfirmationNumber>3364214265</ConfirmationNumber>
                    <RateCode>LV4</RateCode>
                    <Name>CONCUR HOTEL</Name>
                    <HotelPropertyId>CONQ</HotelPropertyId>
                    <CheckinTime>03:00 PM</CheckinTime>
                    <CheckoutTime>12:00 PM</CheckoutTime>
                    <NumPersons>1</NumPersons>
                    <NumRooms>1</NumRooms>
                    <CancellationPolicy>Cxl 1 day prior to Arrival</CancellationPolicy>
                    <DailyRate>240.3500</DailyRate>
                    <Currency>USD</Currency>
                    <RoomDescription>1 KING BED ACCESSIBLE ROOM - K1RRC</RoomDescription>
                    <Charges>
                        <Rate>
                            <Currency>USD</Currency>
                            <Amount>240.3500</Amount>
                            <StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
                            <IsPrimary>false</IsPrimary>
                            <SemanticsCode>ROOMRATE</SemanticsCode>
                            <SemanticsVendorType>H</SemanticsVendorType>
                            <PerUnit>DAY</PerUnit>
                            <NumUnits>3.0000</NumUnits>
                        </Rate>
                    </Charges>
                </Hotel>
            </Segments>
            <Passengers>
                <Passenger>
                    <NameFirst>Chris</NameFirst>
                    <NameLast>Miller</NameLast>
                </Passenger>
            </Passengers>
            <RecordLocator>0987654321</RecordLocator>
            <BookingSource>TravelBookings.com</BookingSource>
            <DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
            <OriginalItinLocator>33491211</OriginalItinLocator>
            <ItinSourceName>ConcurConnectAPI</ItinSourceName>
            <PassengerCount>1</PassengerCount>
        </Booking>
    </Bookings>
</Itinerary>

Response

<Itinerary xmlns="http://www.concursolutions.com/api/travel/trip/2010/06">
    <id>https://www.concursolutions.com/api/travel/trip/v1.1/CNQR1234567890</id>
    <ItinLocator>CNQR1234567890</ItinLocator>
    <ClientLocator>KK-CNQ-1M1P6-5HJ</ClientLocator>
    <ItinSourceName>ConcurTravel</ItinSourceName>
    <TripName>Trip from Dallas to Seattle</TripName>
    <Comments />
    <StartDateLocal>2013-12-21T07:25:00</StartDateLocal>
    <EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
    <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
    <BookedVia>EveryGDS</BookedVia>
    <BookedByFirstName>Chris</BookedByFirstName>
    <BookedByLastName>Miller</BookedByLastName>
    <DateBookedLocal>2012-07-24T19:15:52</DateBookedLocal>
    <Bookings>
        <Booking>
            <Segments>
                <Car>
                    <Vendor>CQ</Vendor>
                    <Status>HK</Status>
                    <StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
                    <EndDateLocal>2013-12-24T12:00:00</EndDateLocal>
                    <ConfirmationNumber>F1672664579</ConfirmationNumber>
                    <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
                    <StartCityCode>SEA</StartCityCode>
                    <EndCityCode>SEA</EndCityCode>
                    <StartLocation>SEA</StartLocation>
                    <EndLocation>SEA</EndLocation>
                    <Class>E</Class>
                    <Body>C</Body>
                    <Transmission>M</Transmission>
                    <AirCondition>R</AirCondition>
                    <NumCars>1</NumCars>
                    <DiscountCode>346660</DiscountCode>
                    <DailyRate>44.0000</DailyRate>
                    <TotalRate>44.0000</TotalRate>
                    <RateType>D</RateType>
                    <Currency>USD</Currency>
                    <Charges>
                        <Fixed>
                            <Description>Dropoff Fee</Description>
                            <Currency>USD</Currency>
                            <Amount>0.0000</Amount>
                            <IsPrimary>false</IsPrimary>
                            <SemanticsCode>DROPOFFFEE</SemanticsCode>
                            <SemanticsVendorType>C</SemanticsVendorType>
                        </Fixed>
                        <RateWithAllowance>
                            <Currency>USD</Currency>
                            <Amount>44.0000</Amount>
                            <StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
                            <IsPrimary>true</IsPrimary>
                            <SemanticsCode>DAYS</SemanticsCode>
                            <SemanticsVendorType>C</SemanticsVendorType>
                            <PerUnit>DAY</PerUnit>
                            <NumUnits>1.0000</NumUnits>
                            <AllowanceNumUnits>250.0000</AllowanceNumUnits>
                            <AllowanceAmount>0.2400</AllowanceAmount>
                            <AllowanceIsUnlimited>false</AllowanceIsUnlimited>
                        </RateWithAllowance>
                    </Charges>
                </Car>
            </Segments>
            <Passengers>
                <Passenger>
                    <NameFirst>Chris</NameFirst>
                    <NameLast>Miller</NameLast>
                </Passenger>
            </Passengers>
            <RecordLocator>C123456789</RecordLocator>
            <BookingSource>ConcurCars</BookingSource>
            <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
            <DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
            <ItinSourceName>TravelSupplier</ItinSourceName>
            <PassengerCount>1</PassengerCount>
        </Booking>
        <Booking>
            <Segments>
                <Hotel>
                    <Vendor>CQ</Vendor>
                    <Status>GK</Status>
                    <StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
                    <EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
                    <ConfirmationNumber>3364214265</ConfirmationNumber>
                    <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
                    <RateCode>LV4</RateCode>
                    <Name>CONCUR HOTEL</Name>
                    <HotelPropertyId>CONQ</HotelPropertyId>
                    <CheckinTime>00:00</CheckinTime>
                    <CheckoutTime>00:00</CheckoutTime>
                    <NumPersons>1</NumPersons>
                    <NumRooms>1</NumRooms>
                    <CancellationPolicy>Cxl 1 day prior to Arrival</CancellationPolicy>
                    <DailyRate>240.3500</DailyRate>
                    <Currency>USD</Currency>
                    <RoomDescription>1 KING BED ACCESSIBLE ROOM - K1RRC</RoomDescription>
                    <Charges>
                        <Rate>
                            <Currency>USD</Currency>
                            <Amount>240.3500</Amount>
                            <StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
                            <IsPrimary>false</IsPrimary>
                            <SemanticsCode>ROOMRATE</SemanticsCode>
                            <SemanticsVendorType>H</SemanticsVendorType>
                            <PerUnit>DAY</PerUnit>
                            <NumUnits>3.0000</NumUnits>
                        </Rate>
                    </Charges>
                </Hotel>
            </Segments>
            <Passengers>
                <Passenger>
                    <NameFirst>Chris</NameFirst>
                    <NameLast>Miller</NameLast>
                </Passenger>
            </Passengers>
            <RecordLocator>0987654321</RecordLocator>
            <BookingSource>ConcurHotel</BookingSource>
            <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
            <DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
            <OriginalItinLocator>33491211</OriginalItinLocator>
            <ItinSourceName>ConcurTravel</ItinSourceName>
            <PassengerCount>1</PassengerCount>
        </Booking>
    </Bookings>
</Itinerary>

This example shows how a TripLink supplier creates a trip.

Request

POST /api/travel/trip/v1.1/ HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
Content-Type: application/xml
...

<Itinerary xmlns="http://www.concursolutions.com/api/travel/trip/2010/06">
    <TripName>Trip from Dallas to Seattle</TripName>
    <TripStatus>HK</TripStatus>
    <Comments />
    <StartDateLocal>2013-12-21T07:25:00</StartDateLocal>
    <EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
    <BookedByFirstName>Chris</BookedByFirstName>
    <BookedByLastName>Miller</BookedByLastName>
    <Bookings>
        <Booking>
            <Segments>
                <Car>
                    <StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
                    <EndDateLocal>2013-12-24T12:00:00</EndDateLocal>
                    <StartCityCode>SEA</StartCityCode>
                    <EndCityCode>SEA</EndCityCode>
                </Car>
            </Segments>
            <Passengers>
                <Passenger>
                    <NameFirst>Chris</NameFirst>
                    <NameLast>Miller</NameLast>
                </Passenger>
            </Passengers>
            <RecordLocator>C123456789</RecordLocator>
            <BookingSource>TravelBookings.com</BookingSource>
            <DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
        </Booking>
        <Booking>
            <Segments>
                <Hotel>
                    <Status>GK</Status>
                    <StartCityCode>SEA</StartCityCode>
                    <StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
                    <EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
                    <TimeZoneId>Pacific</TimeZoneId>
                    <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
                    <StartCity>Seattle</StartCity>
                    <StartCountry>US</StartCountry>
                </Hotel>
            </Segments>
            <Passengers>
                <Passenger>
                    <NameFirst>Chris</NameFirst>
                    <NameLast>Miller</NameLast>
                </Passenger>
            </Passengers>
            <RecordLocator>0987654321</RecordLocator>
            <BookingSource>TravelBookings.com</BookingSource>
            <DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
        </Booking>
    </Bookings>
</Itinerary>

Response

<Itinerary xmlns="http://www.concursolutions.com/api/travel/trip/2010/06">
    <id>https://www.concursolutions.com/api/travel/trip/v1.1/CNQR1234567890</id>
    <ItinLocator>CNQR1234567890</ItinLocator>
    <TripName>Trip from Dallas to Seattle</TripName>
    <TripStatus>HK</TripStatus>
    <Comments />
    <StartDateLocal>2013-12-21T07:25:00</StartDateLocal>
    <EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
    <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
    <BookedVia>EveryGDS</BookedVia>
    <BookedByFirstName>Chris</BookedByFirstName>
    <BookedByLastName>Miller</BookedByLastName>
    <DateBookedLocal>2012-07-24T19:15:52</DateBookedLocal>
    <Bookings>
        <Booking>
            <Segments>
                <Car>
                    <StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
                    <EndDateLocal>2013-12-24T12:00:00</EndDateLocal>
                    <StartCityCode>SEA</StartCityCode>
                    <EndCityCode>SEA</EndCityCode>
                </Car>
            </Segments>
            <Passengers>
                <Passenger>
                    <NameFirst>Chris</NameFirst>
                    <NameLast>Miller</NameLast>
                </Passenger>
            </Passengers>
            <RecordLocator>C123456789</RecordLocator>
            <BookingSource>TravelBookings.com</BookingSource>
            <DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
        </Booking>
        <Booking>
            <Segments>
                <Hotel>
                    <Status>GK</Status>
                    <StartCityCode>SEA</StartCityCode>
                    <StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
                    <EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
                    <TimeZoneId>Pacific</TimeZoneId>
                    <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
                    <StartCity>Seattle</StartCity>
                    <StartCountry>US</StartCountry>
                </Hotel>
            </Segments>
            <Passengers>
                <Passenger>
                    <NameFirst>Chris</NameFirst>
                    <NameLast>Miller</NameLast>
                </Passenger>
            </Passengers>
            <RecordLocator>0987654321</RecordLocator>
            <BookingSource>TravelBookings.com</BookingSource>
            <DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
        </Booking>
    </Bookings>
</Itinerary>

Example 3: Third-Party Developer Creates a Trip Using the Access Token Used to Make the API Call

This example shows how to create a trip for a user whose account is associated with the access token used to make the API call.

Request

POST https://www.concursolutions.com/api/travel/trip/v1.1 HTTPS/1.1
Authorization: OAuth {access token}
Content-Type: application/xml
...

<Itinerary xmlns="http://www.concursolutions.com/api/travel/trip/2010/06">
    <ClientLocator>KK-CNQ-1M1P6-5HJ</ClientLocator>
    <ItinSourceName>ConcurConnectAPI</ItinSourceName>
    <TripName>Trip from Dallas to Seattle</TripName>
    <Comments />
    <StartDateLocal>2013-12-21T07:25:00</StartDateLocal>
    <EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
    <BookedByFirstName>Chris</BookedByFirstName>
    <BookedByLastName>Miller</BookedByLastName>
    <TripStatus>7</TripStatus>
    <TravelRequestId>3339</TravelRequestId>
    <CustomAttributes>
        <CustomAttribute>
            <ExternalId />
            <DataType>Numeric</DataType>
            <Name>ProposalBatchSize</Name>
            <DisplayTitle />
            <Data>3</Data>
            <DisplayOnItinerary>true</DisplayOnItinerary>
        </CustomAttribute>
        <CustomAttribute>
            <ExternalId />
            <DataType>Numeric</DataType>
            <Name>ProposalSequenceIndex</Name>
            <DisplayTitle />
            <Data>1</Data>
            <DisplayOnItinerary>true</DisplayOnItinerary>
        </CustomAttribute>
    </CustomAttributes>
    <Bookings>
        <Booking>
            <Segments>
                <Car>
                    <Vendor>CQ</Vendor>
                    <Status>HK</Status>
                    <StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
                    <EndDateLocal>2013-12-24T12:00:00</EndDateLocal>
                    <ConfirmationNumber>F1672664579</ConfirmationNumber>
                    <StartCityCode>SEA</StartCityCode>
                    <EndCityCode>SEA</EndCityCode>
                    <StartLocation>SEA</StartLocation>
                    <EndLocation>SEA</EndLocation>
                    <Class>E</Class>
                    <Body>C</Body>
                    <Transmission>M</Transmission>
                    <AirCondition>R</AirCondition>
                    <NumCars>1</NumCars>
                    <DiscountCode>346660</DiscountCode>
                    <DailyRate>44.0000</DailyRate>
                    <TotalRate>44.0000</TotalRate>
                    <RateType>D</RateType>
                    <Currency>USD</Currency>
                    <Charges>
                        <Fixed>
                            <Description>Dropoff Fee</Description>
                            <Currency>USD</Currency>
                            <Amount>0.0000</Amount>
                            <IsPrimary>false</IsPrimary>
                            <SemanticsCode>DROPOFFFEE</SemanticsCode>
                            <SemanticsVendorType>C</SemanticsVendorType>
                        </Fixed>
                        <RateWithAllowance>
                            <Currency>USD</Currency>
                            <Amount>44.0000</Amount>
                            <StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
                            <IsPrimary>true</IsPrimary>
                            <SemanticsCode>DAYS</SemanticsCode>
                            <SemanticsVendorType>C</SemanticsVendorType>
                            <PerUnit>DAY</PerUnit>
                            <NumUnits>1.0000</NumUnits>
                            <AllowanceNumUnits>250.0000</AllowanceNumUnits>
                            <AllowanceAmount>0.2400</AllowanceAmount>
                            <AllowanceIsUnlimited>false</AllowanceIsUnlimited>
                        </RateWithAllowance>
                    </Charges>
                </Car>
            </Segments>
            <Passengers>
                <Passenger>
                    <NameFirst>Chris</NameFirst>
                    <NameLast>Miller</NameLast>
                </Passenger>
            </Passengers>
            <RecordLocator>C123456789</RecordLocator>
            <BookingSource>TravelBookings.com</BookingSource>
            <DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
            <ItinSourceName>ConcurConnectAPI</ItinSourceName>
            <PassengerCount>1</PassengerCount>
        </Booking>
        <Booking>
            <Segments>
                <Hotel>
                    <Vendor>CQ</Vendor>
                    <Status>GK</Status>
                    <StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
                    <EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
                    <ConfirmationNumber>3364214265</ConfirmationNumber>
                    <RateCode>LV4</RateCode>
                    <Name>CONCUR HOTEL</Name>
                    <HotelPropertyId>CONQ</HotelPropertyId>
                    <CheckinTime>03:00 PM</CheckinTime>
                    <CheckoutTime>12:00 PM</CheckoutTime>
                    <NumPersons>1</NumPersons>
                    <NumRooms>1</NumRooms>
                    <CancellationPolicy>Cxl 1 day prior to Arrival</CancellationPolicy>
                    <DailyRate>240.3500</DailyRate>
                    <Currency>USD</Currency>
                    <RoomDescription>1 KING BED ACCESSIBLE ROOM - K1RRC</RoomDescription>
                    <Charges>
                        <Rate>
                            <Currency>USD</Currency>
                            <Amount>240.3500</Amount>
                            <StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
                            <IsPrimary>false</IsPrimary>
                            <SemanticsCode>ROOMRATE</SemanticsCode>
                            <SemanticsVendorType>H</SemanticsVendorType>
                            <PerUnit>DAY</PerUnit>
                            <NumUnits>3.0000</NumUnits>
                        </Rate>
                    </Charges>
                </Hotel>
            </Segments>
            <Passengers>
                <Passenger>
                    <NameFirst>Chris</NameFirst>
                    <NameLast>Miller</NameLast>
                </Passenger>
            </Passengers>
            <RecordLocator>0987654321</RecordLocator>
            <BookingSource>TravelBookings.com</BookingSource>
            <DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
            <OriginalItinLocator>33491211</OriginalItinLocator>
            <ItinSourceName>ConcurConnectAPI</ItinSourceName>
            <PassengerCount>1</PassengerCount>
        </Booking>
    </Bookings>
</Itinerary>

Response

The response is the same as in Example 1.

Update a Trip

Creates a new trip or updates an existing trip. A new trip will be created if the trip dates span no existing trip and the request doesn’t include a tripId. If a tripId is included in the URI it will update the specified trip. The full trip information is included in the update request, which replaces the existing trip.

This endpoint can be used to create trips for a user that is not the OAuth consumer. This is most often done when a travel supplier or TMC needs to create a trip on behalf of a user. The supplier or TMC must be registered with SAP Concur and have an SAP Concur account that has one of the following user roles: Web Services Administrator for Professional, or Can Administer for Standard.

Cancel a Trip

This endpoint can be used to cancel all segments in a trip. To cancel a trip on behalf of a user, the OAuth access token used to make the API call should be associated with the SAP Concur account of that user. The TripLink supplier or TMC must be registered with SAP Concur and have an SAP Concur account that has one of the following user roles: Web Services Administrator for Professional, or Can Administer for Standard.

Request

POST /travel/trip/v1.1/cancel?tripid=trip_ID[&userid_type=login&userid_value=login_ID]

Path Parameters

Parameter Name Data Type Description
cancel required string

Request Parameters

Parameter Name Data Type Description
tripid string Optional: The identifier for the trip to be updated. For example, if the value of tripid is I2uwiJJw8r7Owl3IWlSie9WIelxhAhwiL, then the request is POST /travel/trip/v1.1?tripid=I2uwiJJw8r7Owl3IWlSie9WIelxhAhwiL.
userid_type string Optional: The type of user identification to use. Possible value is: login_id.
userid_value string Optional: The user's login ID. This parameter must be provided in conjunction with the userid_type parameter. The userid_type and userid_value parameters can only be used if the user account associated with the OAuth 2.0 access token must have an SAP Concur account with one of these roles: Web Services Administrator for Professional or Can Administer for Standard. The format for the request URI using the userid_type and userid_value query parameters is /travel/trip/v1.1/trip_ID?userid_type=login&userid_value=login_ID.

Headers

Authorization Header (Required)

Authorization: OAuth {access_token}

Where access_token is the OAuth 2.0 access token of the user whose trip you want to create or update. If you want to access company-wide itinerary information, the user account associated with the OAuth 2.0 access token must have an SAP Concur account with one of these roles: Web Services Administrator for Professional or Can Administer for Standard.

Request Content Body

None.

Cancel Trip Request Schema

The request returns the full trip details for the cancelled trip. If the request is successful, the response trip will not contain any segments because they have been cancelled. The response includes the following additional elements inside the Itinerary parent element:

Parameter Name Data Type Description
id string The URI including the trip ID.
ItinLocator string The itinerary locator value (trip ID without the URL). The ItinLocator value is used when updating an existing trip.
DateModifiedUtc dateTime The UTC formatted date that this booking was last modified.
BookedVia string The GDS the itinerary was booked in.
DateBookedLocal dateTime The date, in the traveler’s local time, that the booking was made.

Examples

Example: Cancel a Trip with a Specific Trip ID

Request

POST /api/travel/trip/v1.1/cancel?tripId=CNQR1234567890 HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
...

Response

<Itinerary xmlns="http://www.concursolutions.com/api/travel/trip/2010/06">
    <id>https://www.concursolutions.com/api/travel/trip/v1.1/CNQR1234567890</id>
    <ItinLocator>CNQR1234567890</ItinLocator>
    <ClientLocator>KK-CNQ-1M1P6-5HJ</ClientLocator>
    <ItinSourceName>ConcurTravel</ItinSourceName>
    <TripName>Trip from Dallas to Seattle</TripName>
    <Comments />
    <StartDateLocal>2013-12-21T07:25:00</StartDateLocal>
    <EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
    <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
    <BookedVia>EveryGDS</BookedVia>
    <BookedByFirstName>Chris</BookedByFirstName>
    <BookedByLastName>Miller</BookedByLastName>
    <DateBookedLocal>2012-07-24T19:15:52</DateBookedLocal>
    <Bookings>
        <Booking>
            <Segments/>
            <Passengers>
                <Passenger>
                    <NameFirst>Chris</NameFirst>
                    <NameLast>Miller</NameLast>
                </Passenger>
            </Passengers>
            <RecordLocator>C123456789</RecordLocator>
            <BookingSource>ConcurCars</BookingSource>
            <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
            <DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
            <ItinSourceName>TravelSupplier</ItinSourceName>
            <PassengerCount>1</PassengerCount>
        </Booking>
        <Booking>
            <Segments/>
            <Passengers>
                <Passenger>
                    <NameFirst>Chris</NameFirst>
                    <NameLast>Miller</NameLast>
                </Passenger>
            </Passengers>
            <RecordLocator>0987654321</RecordLocator>
            <BookingSource>ConcurHotel</BookingSource>
            <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
            <DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
            <OriginalItinLocator>33491211</OriginalItinLocator>
            <ItinSourceName>ConcurTravel</ItinSourceName>
            <PassengerCount>1</PassengerCount>
        </Booking>
    </Bookings>
</Itinerary>

USER-PROVISIONING

Spend User v4 - Getting Started

Important: This API is currently in pre-release status and is only available to approved early access participants. The API is under development and might change before being generally released. To become an early access participant, contact your SAP Concur Representative.

Spend User Provisioning allows callers to provision a user in the SAP Concur spend domain. This is an asynchronous downstream process from the User Provisioning v4 service. Currently spend user data can be created, modified, and replaced with the POST, PATCH, and PUT provisioning operations. The retrieval of spend user data is supported through GET endpoints: One that can retrieve a filtered and paginated set of all spend users in a company, and another that can retrieve a specific spend user's data using their unique identifier.

Limitations: This API is only available to partners who have been granted access. Access to this documentation does not provide access to the API.

Getting Started

Products and Editions

Scope Usage

Name Description Endpoint
spend.user.general.read View spend user information. GET
spend.user.general.writeonly Change spend user information. POST, PUT

Note: In addition to the spend scopes, you will need the scopes listed in User Provisioning v4 in order to provision core user data via the /provision/v4/Bulk endpoint.

Dependencies

SAP Concur users must purchase Concur Expense in order to use the spend extensions to provision spend related data. SAP Concur clients must use the User Provisioning v4 API to provision users in order to use this endpoint to retrieve user data.

Access Token Usage

This API currently only supports company level access tokens.

User Provisioning Service

Important: This API is currently in pre-release status and is only available to approved early access participants. The API is under development and might change before being generally released. To become an early access participant, contact your SAP Concur Representative.

The User Provisioning Service allows callers to provision a user in the SAP Concur environment. Once a user is provisioned, the user profile is set up in Identity, Travel, and Spend.

Limitations: This API is only available to partners who have been granted access. Access to this documentation does not provide access to the API.

Process Flow

A process flow diagram of the User Provisioning API

Products and Editions

Scope Usage

Name Description Endpoint
user.provision.write Provision a user. GET, POST, PUT, PATCH
user.provision.read Request status of a provisioning request. GET
identity.user.coreenterprise.writeonly Write access to all core and enterprise extensions except externalID. POST, PUT, PATCH
identity.user.externalID.writeonly Write access to externalID only. POST, PUT, PATCH
identity.user.ids.read Read user ID data. GET
identity.user.core.read Read user core data. GET
identity.user.coresensitive.read Read core sensitive data. GET
identity.user.enterprise.read Read user enterprise data. GET
travel.user.general.read Read general Travel data. GET
travel.user.private.read Read private Travel data. GET
spend.user.general.writeonly Change spend user information. POST, PUT, PATCH
spend.user.general.read View spend user information. GET

Dependencies

SAP Concur users must purchase either Concur Expense or Concur Travel or both in order to use this API. This API only available to approved early adopter partners and clients. Please contact your SAP Concur representative for more information.

Access Token Usage

This API supports company level access tokens.

Events

UPS supports post event notification when provisioning process is complete.

https://developer.concur.com/api-reference/callouts/post-event-notification.html

Event Type: * ProvisioningComplete

Create a Provisioning Request for One or More Users

Creates one or more provisioning requests.

Scopes

Request

POST https://www.us.api.concursolutions.com/provisioning/v4/Bulk/

URI

Template
POST /provisioning/v4/Bulk/

Parameters

None

Headers

Payload

Response

Status Codes

Payload

None

Example

Request

The maximum file size allowed is 100 operations or 400kb per request.

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:BulkRequest"
    ],
    "failOnErrors": 1,
    "Operations": [
        {
            "method": "POST",
            "path": "/Users",
            "bulkId": "bulk-operation-1",
            "data": {
                "userName": "Chris.doe198@sap.com",
                "active": true,
                "name": {
                    "formatted": "Chris Doe",
                    "legalName": "Chris Doe",
                    "familyName": "Doe",
                    "givenName": "Chris"
                },
                "emails": [
                    {
                        "value": "Chris.doe198@sap.com",
                        "type": "work"
                    }
                ],
        "timezone": "America/Los_Angeles",
                "entitlements": [
                    "Expense",
                    "Travel"
                ],
                "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
                    "employeeNumber": "3749",
                    "companyId": "xxxxxxxx-xxx-xxx-xxx-9300b1c317xxx"
                }
            }
        }
    ]
}

Response

202 Accepted
Content-Type: application/json
{
    "schemas": [
        "urn:ietf:params:scim:schemas:extension:concur:2.0:Provision:Status"
    ],
    "id": "9ff00c90-1c35-4fd1-8ac7-db8b9be70a98",
    "operationsCount": {
        "total": 1,
        "success": 1,
        "failed": 0,
        "pending": 0
    },
    "status": {
        "completed": false,
        "success": null
    },
    "meta": {
        "location": "https://us.api.concursolutions.com/provisioning/v4/provisions/9ff00c90-1c35-4fd1-8ac7-db8b9be70a98/status",
        "created": "2021-04-26T16:29:38.459+0000",
        "lastModified": "2021-04-26T16:29:38.459+0000",
        "provisionType": "Bulk",
        "resourceType": "ProvisionRequest",
        "correlationId": "a2e9973f-516a-4203-ab86-b3d592fc0d5b"
    }
}

Update One or More Provisioning Requests

Updates one or more provisioning requests.

Scopes

Request

PATCH https://www.us.api.concursolutions.com/provisioning/v4/Bulk/

URI

Template
PATCH /provisioning/v4/Bulk/

Parameters

None.

Headers

Payload

Bulk Request

Response

Status Codes

Payload

None

Example

Request

PATCH https://www.us.api.concursolutions.com/provisioning/v4/Bulk/
{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:BulkRequest",
        "urn:ietf:params:scim:api:messages:2.0:PatchOp"
    ],
    "failOnErrors": 1,
    "Operations": [
        {
            "method": "PATCH",
            "path": "/Users/8f545a90-305f-441b-91cd-a69ad5f548f5",
            "data": {
                "Operations": [

                    {
                        "op": "add",
                        "path": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department",
                        "value": "Engineering"
                    },
                    {
                        "op": "replace",
                        "path": "userName",
                        "value":
                            "Updated_Chris_Doe_Name@sap.com"

                    }
                ]
            }
        }
    ]
}

Response

202 Accepted
Content-Type: application/json
{
    "schemas": [
        "urn:ietf:params:scim:schemas:extension:concur:2.0:Provision:Status"
    ],
    "id": "193975e3-f9b2-4786-813d-b209ee0f8527",
    "operationsCount": {
        "total": 1,
        "success": 0,
        "failed": 0,
        "pending": 1
    },
    "status": {
        "completed": true,
        "success": true
    },
    "meta": {
        "location": "https://us.api.concursolutions.com/provisioning/v4/provisions/193975e3-f9b2-4786-813d-b209ee0f8527/status",
        "created": "2021-04-26T16:47:44.009+0000",
        "lastModified": "2021-04-26T16:47:44.009+0000",
        "provisionType": "Bulk",
        "resourceType": "ProvisionRequest",
        "correlationId": "96f93318-8fb1-4949-b4ed-b4316455b032"
    }
}

Replace One or More Resources

Replaces one or more existing resources. In the case where all attributes are not provisioned, system default values will be provisioned.

Scopes

Request

PUT https://www.us.api.concursolutions.com/provisioning/v4/Bulk/

URI

Template
PUT /provisioning/v4/Bulk/

Parameters

None.

Headers

Payload

Bulk Request

Response

Status Codes

Payload

None

Example

Request

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:BulkRequest"
    ],
    "failOnErrors": 1,
    "Operations": [
        {
            "method": "PUT",
            "path": "/Users/8f545a90-305f-441b-91cd-a69ad5f548f5",
            "bulkId": "Seattle",
            "data": {
                "id": "8f545a90-305f-441b-91cd-a69ad5f548f5",
                "userName": "john.doe21224@sap.com",
                "active": false,
                "name": {
                    "formatted": "Mr. John Doe",
                    "legalName": "Mr. John Doe",
                    "middleName": "Joe",
                    "middleInitial": "J",
                    "familyName": "Doe",
                    "givenName": "John",
                    "honorificPrefix": "Prof Dr Mr",
                    "honorificSuffix": "VI",
                    "hasNoMiddleName": true
                },
                "emails": [
                    {
                        "value": "john.doe193@sap.com",
                        "type": "work"
                    }
                ]
            }
        }
    ]
}

Response

202 Accepted
Content-Type: application/json
{
    "schemas": [
        "urn:ietf:params:scim:schemas:extension:concur:2.0:Provision:Status"
    ],
    "id": "a43fd01c-fc99-4cf1-a16e-6f440b797603",
    "operationsCount": {
        "total": 1,
        "success": 1,
        "failed": 0,
        "pending": 0
    },
    "status": {
        "completed": true,
        "success": true
    },
    "meta": {
        "location": "https://us.api.concursolutions.com/provisioning/v4/provisions/a43fd01c-fc99-4cf1-a16e-6f440b797603/status",
        "created": "2021-04-26T16:57:39.719+0000",
        "lastModified": "2021-04-26T16:57:39.719+0000",
        "provisionType": "Bulk",
        "resourceType": "ProvisionRequest",
        "correlationId": "dbe2c569-3662-46e7-8521-e6ba77a014ef"
    }
}

Create a User Provisioning Request

Allows the creation of a single user resource.

Scopes

Request

POST https://www.us.api.concursolutions.com/provisioning/v4/Users/

URI

Template
POST /provisioning/v4/Users/

Parameters

None

Headers

Payload

Request

Status Codes

Payload

None

Example

Request

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "userName": "John4_29_4@cs-sso-us-prod.com",

    "active": true,
    "name": {
        "formatted": "Mr. John Doe",
        "legalName": "Mr. John Doe",
        "middleName": "Joe",
        "middleInitial": "J",
        "familyName": "Doe",
        "givenName": "John",
        "honorificPrefix": "Prof Dr Mr",
        "honorificSuffix": "VI",
        "hasNoMiddleName": false
    },

    "emails": [
        {
            "value": "John4_29_4@cs-sso-us-prod.com",
            "type": "work"
        }
    ],
    "entitlements": [
        "Expense",
        "Invoice",
        "Locate",
        "Request",
        "Travel"
    ],
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
        "employeeNumber": "John4_29_4@cs-sso-us-prod.com",
        "companyId": "aa076ada-80a9-4f57-8e98-9300b1c3171d"
    },
    "urn:ietf:params:scim:schemas:extension:spend:2.0:User": {
        "locale": "en-US",
        "country": "US",
        "stateProvince": "WA",
        "ledgerCode": "DEFAULT",
        "reimbursementCurrency": "USD",
        "cashAdvanceAccountCode": "Code",
        "customData": [
            {
                "id": "custom1",
                "value": "testing"
            },
            {
                "id": "orgUnit1",
                "value": "testDepartment"
            }
        ]
    },
    "urn:ietf:params:scim:schemas:extension:spend:2.0:WorkflowPreference": {
        "emailStatusChangeOnCashAdvance": true,
        "emailAwaitApprovalOnCashAdvance": true,
        "emailStatusChangeOnReport": true,
        "emailAwaitApprovalOnReport": true,
        "promptForApproverOnReportSubmit": true,
        "emailStatusChangeOnTravelRequest": true,
        "emailAwaitApprovalOnTravelRequest": true,
        "promptForApproverOnTravelRequestSubmit": true,
        "emailStatusChangeOnPayment": true,
        "emailAwaitApprovalOnPayment": true,
        "promptForApproverOnPaymentSubmit": true,
        "promptForCardTransactionsOnReport": true
    },
    "urn:ietf:params:scim:schemas:extension:spend:2.0:UserPreference": {
        "allowCreditCardTransArrivalEmails": true,
        "defaultReportPrintFormat": "DETAILED",
        "showInstructHelpPanel": true,
        "expenseAuditRequired": "ALWAYS",
        "showImagingIntro": true,
        "allowReceiptImageAvailEmails": true,
        "autoAddTripCardTransOnReport": true,
        "processorReportAccess": "All reports excluding returned",
        "promptForCardTransactionsOnReport": true,
        "promptForReportPrintFormat": true,
        "showExpenseOnReport": "ALL",
        "showTotalOnReport": true,
        "useQuickItinAsDefault": false
    },
    "urn:ietf:params:scim:schemas:extension:spend:2.0:Role": {
        "roles": [
            {
                "roleName": "EXP_APPROVER",
                "roleGroups": []
            }
        ]
    },
    "urn:ietf:params:scim:schemas:extension:spend:2.0:Approver": {
        "report": [
            {
                "approver": {
                    "value": "d1eb15c1-ac9b-40d6-b5f7-ea2d2f5ae8a7",
                    "$ref": "https://www.concursoultions.com/users/approver2",
                    "displayName": "test.employee@sap.com",
                    "employeeNumber": "37480"
                },
                "primary": true
            }
        ]
    }
}

Response

201 Created
Content-Type: application/json
{
    "meta": {
        "resourceType": "User",
        "created": "2021-04-26T20:07:55.000097Z",
        "lastModified": "2021-04-26T20:07:55.000097Z",
        "version": 0,
        "location": "https://us.api.concursolutions.com/profile/identity/v4/Users/ef0bffaf-863f-4b3e-9c4c-bd9c9a8b2ea7",
        "statusUrl": "https://us.api.concursolutions.com/provisioning/v4/provisions/2b41c0c1-15f7-41cc-99bb-a82b5da128a2/status",
        "provisionId": "2b41c0c1-15f7-41cc-99bb-a82b5da128a2"
    },
    "displayName": "John",
    "name": {
        "middleInitial": "J",
        "middleName": "Joe",
        "formatted": "Doe, John Joe",
        "honorificPrefix": "Prof Dr Mr",
        "legalName": "Mr. John Doe",
        "familyName": "Doe",
        "givenName": "John",
        "honorificSuffix": "VI"
    },
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
        "urn:ietf:params:scim:schemas:extension:sap:2.0:User"
    ],
    "active": true,
    "id": "ef0bffaf-863f-4b3e-9c4c-bd9c9a8b2ea7",
    "emails": [
        {
            "value": "John4_29_4@cs-sso-us-prod.com",
            "type": "work",
            "notifications": false,
            "verified": false
        }
    ],
    "userName": "John4_26_1@cs-sso-us-prod.com",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
        "employeeNumber": "John4_29_4@cs-sso-us-prod.com",
        "companyId": "aa076ada-xxxx-xxxx-xxxx-9300b1c3171d"

    }
}

Update the Profile Data of a User

Allows the modification of a single resource.

Scopes

Request

PATCH https://www.us.api.concursolutions.com/provisioning/v4/Users/<Concur UUID>

URI

Template
PATCH /provisioning/v4/Users/

Parameters

Name Type Format Description
id string UUID The SAP Concur platform UUID of the user to be updated.

Headers

Payload

Response

Status Codes

Payload

None

Example

Request

PATCH https://www.us.api.concursolutions.com/provisioning/v4/Users/ef0bffaf-863f-4b3e-9c4c-bd9c9a8b2ea7
{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:PatchOp"
    ],
    "Operations": [
        {
            "op": "add",
            "path": "entitlements",
            "value": [
                "Expense",
                "Invoice",
                "Locate",
                "Request",
                "Travel"
            ]
        },
        {
            "op": "replace",
            "path": "userName",
            "value": "John10_9_1_Replacement@sap.com"
        }
    ]
}

Response

200 OK
Content-Type: application/json
{
    "addresses": null,
    "meta": {
        "resourceType": "User",
        "created": "2021-04-26T20:07:55.000097Z",
        "lastModified": "2021-04-26T20:18:33.000701Z",
        "version": 3,
        "location": "https://us.api.concursolutions.com/profile/identity/v4/Users/ef0bffaf-863f-4b3e-9c4c-bd9c9a8b2ea7",
        "statusUrl": "https://us.api.concursolutions.com/provisioning/v4/provisions/e820c001-c358-4a3e-964a-321dc2a76203/status",
        "provisionId": "e820c001-c358-4a3e-964a-321dc2a76203"
    },
    "displayName": "John",
    "name": {
        "legalName": "Mr. John Doe",
        "honorificSuffix": "VI",
        "middleInitial": "J",
        "formatted": "Doe, John Joe",
        "familyName": "Doe",
        "givenName": "John",
        "honorificPrefix": "Prof Dr Mr",
        "middleName": "Joe"
    },
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
        "urn:ietf:params:scim:schemas:extension:sap:2.0:User"
    ],
    "active": true,
    "id": "ef0bffaf-863f-4b3e-9c4c-bd9c9a8b2ea7",
    "emails": [
        {
            "verified": false,
            "type": "work",
            "value": "John4_26_1@cs-sso-us-prod.com",
            "notifications": false
        }
    ],
    "userName": "John_Updated_76@cs-sso-us-prod.com",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
        "companyId": "aa076ada-80a9-4f57-8e98-9300b1c3171d",
        "employeeNumber": "John_Updated_56@cs-sso-us-prod.com"
    }
}

Replace a User Resource

Allows the replacement of an existing resource. In the case where all attributes are not provisioned, system default values will be provisioned.

Scopes

Request

PUT https://www.us.api.concursolutions.com/provisioning/v4/Users/<Concur UUID>

URI

Template
PUT /provisioning/v4/Users/

Parameters

Name Type Format Description
id string UUID The SAP Concur platform UUID of the user to be updated.

Headers

Payload

Request

Status Codes

Payload

None

Example

Request

PUT https://www.us.api.concursolutions.com/provisioning/v4/Users/ef0bffaf-863f-4b3e-9c4c-bd9c9a8b2ea7

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "userName": "John10_14_1_Replacement@sap.com",
    "id": "8f545a90-305f-441b-91cd-a69ad5f548f5",
    "active": false,
    "name": {
        "formatted": "Mr. John Doe1",
        "legalName": "Mr. John Doe1",
        "middleName": "Joe1",
        "middleInitial": "J",
        "familyName": "Doe1",
        "givenName": "John1",
        "hasNoMiddleName": true
    },
    "emails": [
        {
            "value": "John10_14_1_Replacement@sap.com",
            "type": "work"
        }
    ],
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
        "employeeNumber": "John10_8_1",
        "companyId": "aa076ada-xxxx-xxxx-xxxx-9300b1c3171d"
    }
}

Response

200 OK
Content-Type: application/json
{
    "meta": {
        "resourceType": "User",
        "created": "2021-04-29T17:17:47.000380Z",
        "lastModified": "2021-04-29T17:17:47.000380Z",
        "version": 0,
        "location": "https://us.api.concursolutions.com/profile/identity/v4/Users/61bd5549-d68c-407b-8228-9590ae40eaa0",
        "statusUrl": "https://us.api.concursolutions.com/provisioning/v4/provisions/03295e27-c9c2-4579-92d8-8b46ec91eff5/status",
        "provisionId": "03295e27-c9c2-4579-92d8-8b46ec91eff5"
    },
    "displayName": "John",
    "name": {
        "middleInitial": "J",
        "middleName": "Joe",
        "formatted": "Doe, John Joe",
        "honorificPrefix": "Prof Dr Mr",
        "legalName": "Mr. John Doe",
        "familyName": "Doe",
        "givenName": "John",
        "honorificSuffix": "VI"
    },
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
        "urn:ietf:params:scim:schemas:extension:sap:2.0:User"
    ],
    "active": true,
    "id": "61bd5549-d68c-407b-8228-9590ae40eaa0",
    "emails": [
        {
            "value": "John4_29_4@cs-sso-us-prod.com",
            "type": "work",
            "notifications": false,
            "verified": false
        }
    ],
    "userName": "John4_29_4@cs-sso-us-prod.com",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
        "employeeNumber": "John4_29_4@cs-sso-us-prod.com",
        "companyId": "aa076ada-80a9-4f57-8e98-9300b1c3171d"
    }
}

Retrieve User Profile Data

To retrieve profile data for a specific user, the SAP Concur platform has enabled separate endpoints. For additional information for provisioning the specific profiles, please see the documentation for Identity, Spend, and Travel.

Scopes

Request

GET https://us.api.concursolutions.com/profile/identity/v4/Users

Request Example

GET https://us.api.concursolutions.com/profile/identity/v4/Users/8f545a90-305f-441b-91cd-a69ad5f548f5 
GET https://us.api.concursolutions.com/profile/spend/v4/Users/8f545a90-305f-441b-91cd-a69ad5f548f5
GET https://us.api.concursolutions.com/profile/travel/v4/Users/8f545a90-305f-441b-91cd-a69ad5f548f5

Parameters

Name Type Format Description
ID string - Requested user’s UUID

Headers

Payload

None

Response

Status Codes

Payload

Example

Request

GET https://us.api.concursolutions.com//profile/identity/v4/Users/ef0bffaf-863f-4b3e-9c4c-bd9c9a8b2ea7

Response

200 OK
Content-Type: application/json

Identity

{
    "localeOverrides": {
        "preferenceEndDayViewHour": 20,
        "preferenceFirstDayOfWeek": "Sunday",
        "preferenceDateFormat": "mm/dd/yyyy",
        "preferenceCurrencySymbolLocation": "BeforeAmount",
        "preferenceHourMinuteSeparator": ":",
        "preferenceDefaultCalView": "month",
        "preference24Hour": "H:mm",
        "preferenceNumberFormat": "1,000.00",
        "preferenceStartDayViewHour": 8,
        "preferenceNegativeCurrencyFormat": "-100"
    },
    "addresses": [
        {
            "country": "US",
            "streetAddress": "911 Universal City Plaza",
            "postalCode": "91608",
            "locality": "Hollywood",
            "type": "home",
            "region": "CA"
        }
    ],
    "timezone": "America/New_York",
    "meta": {
        "resourceType": "User",
        "created": "2020-09-22T14:26:29.000516Z",
        "lastModified": "2021-02-10T23:14:18.000733Z",
        "version": 16,
        "location": "https://us.api.concursolutions.com/profile/identity/v4/Users/8f545a90-305f-441b-91cd-a69ad5f548f5"
    },
    "displayName": "John",
    "name": {
        "middleInitial": "J",
        "middleName": "Joe",
        "formatted": "Doe, John Joe",
        "honorificPrefix": "Prof Dr Mr",
        "legalName": "Mr. John Doe",
        "familyName": "Doe",
        "givenName": "John",
        "honorificSuffix": "VI",
        "hasNoMiddleName": false
    },
    "phoneNumbers": [
        {
            "type": "home",
            "value": "tel:555-555-5555",
            "operatingSystem": null,
            "notifications": false,
            "primary": false
        }
        ...
    ],
    "emergencyContacts": [
        {
            "country": "US",
            "streetAddress": "911 Universal City Plaza  Hollywood, CA 91608 US",
            "postalCode": "91608",
            "name": "Emergency Contact",
            "locality": null,
            "phones": [
                "555-555-5555"
            ],
            "region": "CA",
            "relationship": "Other"
        }
    ],
    "preferredLanguage": "en-US",
    "title": "Software Engineer",
    "dateOfBirth": null,
    "nickName": "Francis",
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
        "urn:ietf:params:scim:schemas:extension:sap:2.0:User"
    ],
    "externalId": "1234abcd56789e4370",
    "active": true,
    "id": "8f545a90-305f-441b-91cd-a69ad5f548f5",
    "gender": null,
    "emails": [
        {
            "verified": false,
            "type": "work",
            "value": "john.doe194@BravoPro7.com",
            "notifications": true
        }
        ...
        {
            "verified": false,
            "type": "other2",
            "value": "john.doe1883@BravoPro7.com",
            "notifications": false
        }
    ],
    "userName": "john.doe_replacement@BravoPro7.com",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
        "employeeNumber": "13749670",
        "companyId": "aa076ada-80a9-xxxx-xxxx-9300b1c3171d",
        "department": "Engineering",
        "division": "Theme Park",
        "startDate": "2020-09-22T14:26:00.000",
        "costCenter": null,
        "manager": null,
        "terminationDate": null,
        "orgUnit": null,
        "jobTitle": "Software Engineer"
    }
}

Travel

{
    "id": "8f545a90-305f-441b-91cd-a69ad5f548f5",
    "urn:ietf:params:scim:schemas:extension:travel:2.0:User": {
        "ruleClass": {
            "name": "Default Travel Class",
            "id": 560485
        },
        "travelCrsName": null,
        "xmlProfileSyncId": "",
        "travelNameRemark": "",
        "orgUnit": null,
        "customFields": [
            {
                "name": "Canary ID"
            }

           ...

           {
                "name": "trainline trip purpose 1"
            }
        ],
        "manager": null,
        "groups": []
    }

Spend

{
    "schemas": [
        "urn:com.concur.spend.user.model.scim.ScimResource",
        "urn:ietf:params:scim:schemas:extension:spend:2.0:Role",
        "urn:ietf:params:scim:schemas:extension:spend:2.0:WorkflowPreference",
        "urn:ietf:params:scim:schemas:extension:spend:2.0:User",
        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:Payroll",
        "urn:ietf:params:scim:schemas:extension:spend:2.0:UserPreference",
        "urn:ietf:params:scim:schemas:extension:spend:2.0:Delegate",
        "urn:ietf:params:scim:schemas:extension:spend:2.0:Approver"
    ],
    "id": "8f545a90-305f-441b-91cd-a69ad5f548f5",
    "externalId": null,
    "meta": null,
    "urn:ietf:params:scim:schemas:extension:spend:2.0:Role": {
        "roles": [
            {
                "roleName": "REPORTING_CONFIG_ADMIN"
            }
            ...
            {
                "roleName": "EXP_USER"
            }
        ]
    },
    "urn:ietf:params:scim:schemas:extension:spend:2.0:WorkflowPreference": {
        "emailStatusChangeOnCashAdvance": true,
        "emailAwaitApprovalOnCashAdvance": true,
        "emailStatusChangeOnReport": true,
        "emailAwaitApprovalOnReport": true,
        "promptForApproverOnReportSubmit": true,
        "emailStatusChangeOnTravelRequest": true,
        "emailAwaitApprovalOnTravelRequest": true,
        "promptForApproverOnTravelRequestSubmit": true,
        "emailStatusChangeOnPayment": true,
        "emailAwaitApprovalOnPayment": true,
        "promptForApproverOnPaymentSubmit": true
    },
    "urn:ietf:params:scim:schemas:extension:spend:2.0:User": {
        "reimbursementCurrency": "USD",
        "reimbursementType": "ADP_PAYROLL",
        "ledgerCode": "DEFAULT",
        "country": "US",
        "stateProvince": "WA",
        "locale": "en-US",
        "testEmployee": false,
        "nonEmployee": false,
        "customData": [
            {
                "id": "custom20",
                "value": "testing"
            }
            ...
            {
                "id": "custom18",
                "value": "testing"
            }
        ]
    },
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:Payroll": {
        "adp": {
            "companyCode": "string",
            "deductionCode": "string",
            "employeeFileNumber": "string"
        }
    },
    "urn:ietf:params:scim:schemas:extension:spend:2.0:UserPreference": {
        "showImagingIntro": true,
        "expenseAuditRequired": "ALWAYS",
        "allowCreditCardTransArrivalEmails": true,
        "allowReceiptImageAvailEmails": true,
        "promptForCardTransactionsOnReport": true,
        "autoAddTripCardTransOnReport": true,
        "promptForReportPrintFormat": true,
        "defaultReportPrintFormat": "DETAILED",
        "showTotalOnReport": true,
        "showExpenseOnReport": "PARENT",
        "showInstructHelpPanel": true,
        "useQuickItinAsDefault": false
    },
    "urn:ietf:params:scim:schemas:extension:spend:2.0:Delegate": {},
    "urn:ietf:params:scim:schemas:extension:spend:2.0:Approver": {
        "report": [
            {
                "approver": {
                    "value": "7a183cbe-1f4a-44f4-891c-8eff3608975e"
                },
                "primary": true
            }
        ]
        ...
        "budget": [
            {
                "approver": {
                    "value": "7a183cbe-1f4a-44f4-891c-8eff3608975e"
                },
                "primary": true
            }
        ]
    }
}

Retrieve a Summary Provisioning Request Status

Retrieves a summary provisioning request status.

Scopes

user.provision.read- Refer to Scope Usage for full details.

Request

URI

Template
GET /provisioning/v4/provisions/{provision-id}/status
Parameters
Name Type Format Description
provision-id string - The provisioning request UUID

Headers

Payload

None

Response

Status Codes

Payload

Provision Status

Example

Request

GET https://www.us.api.concursolutions.com/provisioning/v4/provisions/0e00f6a4-6798-4f66-9f47-1e944b619b2e/status

Response

200 OK
Content-Type: application/json
{
    "schemas": [
        "urn:ietf:params:scim:schemas:extension:concur:2.0:Provision:Status"
    ],
    "id": "14b15c4b-59a1-42fb-bdb5-999bb3d38d5d",
    "operationsCount": {
        "total": 1,
        "success": 1,
        "failed": 0,
        "pending": 0
    },
    "status": {
        "completed": true,
        "success": true
    },
  "meta": {
    "location": "https://www.us.api.concursolutions.com/provisioning/v4/provisions/0e00f6a4-6798-4f66-9f47-1e944b619b2e/status",
    "created": "2020-07-15T23:03:07.859+0000",
    "lastModified": "2020-07-15T23:03:07.859+0000",
    "resourceType": "ProvisionRequest",
    "correlationId": "d5192a1d-3385-4afc-9e8d-4aeff8b58a48"
    }
}

Retrieve a Detailed Provisioning Request Status

Retrieves a detailed provisioning request status.

Scopes

user.provision.read- Refer to Scope Usage for full details.

Request

GET https://www.us.api.concursolutions.com/provisioning/v4/provisions/{provision-id}/status?attributes=operations

Parameters

Name Type Format Description
attributes string operations Response includes operations when specified.
startIndex Integer Non-negative Integer The 1-based index of the first result in the current set of list results.
count Integer Non-negative Integer Specifies the desired operations per page.
state string status Can filter results based on:[pending, success, failed]

Headers

Payload

None

Response

Status Codes

Payload

Provision Status

Example

Request

GET https://www.us.api.concursolutions.com/provisioning/v4/provisions/0e00f6a4-6798-4f66-9f47-1e944b619b2e/status?attributes=operations

Response

200 OK
Content-Type: application/json
{
    "itemsPerPage": 1,
    "meta": {
        "location": "https://us.api.concursolutions.com/provisioning/v4/provisions/0e00f6a4-6798-4f66-9f47-1e944b619b2e/status",
        "created": "2021-04-22T15:03:25.975+0000",
        "lastModified": "2021-04-22T15:03:27.558+0000",
        "provisionType": "User",
        "resourceType": "ProvisionRequest",
        "correlationId": "5d15903c-1921-49f1-8d29-329525bb4a4f",
        "completed": "2021-04-22T15:03:27.558+0000"
    },
    "operationsCount": {
        "total": 1,
        "success": 1,
        "failed": 0,
        "pending": 0
    },
    "totalResults": 1,
    "schemas": [
        "urn:ietf:params:scim:schemas:extension:concur:2.0:Provision:Status"
    ],
    "status": {
        "completed": true,
        "success": true
    },
    "id": "ef0bffaf-863f-4b3e-9c4c-bd9c9a8b2ea7",
    "operations": [
        {
            "id": "1",
            "status": {
                "completed": true,
                "success": true
            },
            "resource": {
                "id": "46702256-0123-4e83-83ff-d1a55adfc607",
                "type": "User"
            },
            "bulkId": "gen-temp-bulk-id",
            "extensions": [
                {
                    "name": "urn:ietf:params:scim:schemas:extension:spend:2.0:WorkflowPreference",
                    "status": {
                        "completed": true,
                        "success": true,
                        "code": "200",
                        "result": "no-op"
                    }
                },
                {
                    "name": "urn:ietf:params:scim:schemas:extension:spend:2.0:Role",
                    "status": {
                        "completed": true,
                        "success": true,
                        "code": "200",
                        "result": "no-op"
                    }
                },
                {
                    "name": "urn:ietf:params:scim:schemas:extension:spend:2.0:UserPreference",
                    "status": {
                        "completed": true,
                        "success": true,
                        "code": "200",
                        "result": "no-op"
                    }
                },
                {
                    "name": "urn:ietf:params:scim:schemas:extension:spend:2.0:Approver",
                    "status": {
                        "completed": true,
                        "success": true,
                        "code": "200",
                        "result": "no-op"
                    }
                },
                {
                    "name": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:Payroll",
                    "status": {
                        "completed": true,
                        "success": true,
                        "code": "200",
                        "result": "no-op"
                    }
                },
                {
                    "name": "urn:ietf:params:scim:schemas:core:2.0:User",
                    "status": {
                        "completed": true,
                        "success": true,
                        "code": "200",
                        "result": "success"
                    }
                },
                {
                    "name": "urn:ietf:params:scim:schemas:extension:spend:2.0:User",
                    "status": {
                        "completed": true,
                        "success": true,
                        "code": "200",
                        "result": "no-op"
                    }
                },
                {
                    "name": "urn:ietf:params:scim:schemas:extension:spend:2.0:Delegate",
                    "status": {
                        "completed": true,
                        "success": true,
                        "code": "200",
                        "result": "no-op"
                    }
                },
                {
                    "name": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
                    "status": {
                        "completed": true,
                        "success": true,
                        "result": "success"
                    }
                },
                {
                    "name": "urn:ietf:params:scim:schemas:extension:travel:2.0:User",
                    "status": {
                        "completed": true,
                        "success": true,
                        "code": "200",
                        "result": "no-op"
                    }
                }
            ]
        }
    ],
    "startIndex": 1
}

Retrieve Supported Resource Types

Retrieves supported resource types.

Scopes

user.provision.read- Refer to Scope Usage for full details.

Request

URI

Template
GET /provisioning/v4/ResourceTypes
Parameters

None

Headers

Payload

-

Response

Status Codes

Payload

None

Example

Request

GET https://www.us.api.concursolutions.com/provisioning/v4/ResourceTypes

Response

200 OK
Content-Type: application/json
[
    {
        "schemas": [
            "urn:ietf:params:scim:schemas:core:2.0:ResourceType"
        ],
        "id": "User",
        "name": "User",
        "endpoint": "/Users",
        "description": "Concur User",
        "schema": "urn:ietf:params:scim:schemas:core:2.0:User",
        "schemaExtensions": [
            {
                "schema": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
                "required": true
            },
            {
                "schema": "urn:ietf:params:scim:schemas:extension:travel:2.0:User",
                "required": false
            },
            {
                "schema": "urn:ietf:params:scim:schemas:extension:spend:2.0:User",
                "required": false
            },
            {
                "schema": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:Payroll",
                "required": false
            },
            {
                "schema": "urn:ietf:params:scim:schemas:extension:spend:2.0:Approver",
                "required": false
            },
            {
                "schema": "urn:ietf:params:scim:schemas:extension:spend:2.0:Delegate",
                "required": false
            },
            {
                "schema": "urn:ietf:params:scim:schemas:extension:spend:2.0:Role",
                "required": false
            },
            {
                "schema": "urn:ietf:params:scim:schemas:extension:spend:2.0:WorkflowPreference",
                "required": false
            },
            {
                "schema": "urn:ietf:params:scim:schemas:extension:spend:2.0:UserPreference",
                "required": false
            }
        ],
        "meta": {
            "location": "https://us.api.concursolutions.com.com/provisioning/v4/ResourceTypes/User",
            "resourceType": "ResourceType"
        }
    }
]

Retrieve Supported Schemas

Retrieves supported schemas.

Scopes

user.provision.read- Refer to Scope Usage for full details.

Request

URI

Template
GET /provisioning/v4/Schemas
Parameters

None

Headers

Payload

None

Response

Status Codes

Payload

None

Example

Request

GET https://www.us.api.concursolutions.com/provisioning/v4/Schemas

Response

200 OK
Content-Type: application/json
[
    {
      "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "Resources": [
        {
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:Schema"
            ],
            "id": "urn:ietf:params:scim:api:messages:concur:2.0:Error",
            "name": "Concur Error",
            "type": "complex",
            "description": "Concur Error",
            "attributes": [
                {
                    "name": "messages",
                    "type": "complex",
                    "multiValue": true,
                    "description": "Additional messages in case of errors / warnings",
                    "mutabbility": "readOnly",
                    "required": false,
                    "subAttributes": [
                        {
                            "name": "code",
                            "type": "string",
                            "description": "Message Code",
                            "mutabbility": "readOnly",
                            "required": true
                        },
                        {
                            "name": "message",
                            "type": "string",
                            "description": "Message description",
                            "mutabbility": "readOnly",
                            "required": false
                        },
                        {
                            "name": "schemaPath",
                            "type": "string",
                            "description": "Relative schema path of attribute",
                            "mutabbility": "readOnly",
                            "required": false
                        },
                        {
                            "name": "type",
                            "type": "string",
                            "description": "Message Type",
                            "mutabbility": "readOnly",
                            "required": true,
                            "canonicalValues": [
                                "error",
                                "warning"
                            ]
                        }
                    ]
                }
            ],
            "meta": {
                "resourceType": "schemas"
            }
        },
        {
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:Schema"
            ],
            "id": "urn:ietf:params:scim:schemas:extension:concur:2.0:Provision:Status",
            "name": "Provision Status",
            "type": "complex",
            "description": "Provision Status",
            "attributes": [
                {
                    "mutability": "readOnly",
                    "description": "Unique identifier (uuid) for the provisioning request",
                    "returned": "always",
                    "name": "id",
                    "multiValued": false,
                    "type": "string",
                    "uniqueness": "global",
                    "caseExact": false,
                    "required": true
                },
                {
                    "mutability": "readOnly",
                    "description": "Status of the provision request",
                    "returned": "always",
                    "subAttributes": [
                        {
                            "name": "completed",
                            "type": "boolean",
                            "description": "Is provisioning completed?",
                            "mutability": "readOnly",
                            "required": true
                        },
                        {
                            "name": "success",
                            "type": "boolean",
                            "description": "Is provisioning successful?",
                            "mutabbility": "readOnly",
                            "required": false
                        }
                    ],
                    "name": "status",
                    "multiValued": false,
                    "type": "complex",
                    "caseExact": true,
                    "required": true
                },

Schema

User

Name Type Format Description
active boolean true/false Required if true, the user is active.
addresses object - A physical mailing address for this user. Supported values: work, home, other
country string - A two-letter country code defined in ISO 3166-1 alpha-2.
locality string - The city or locality.
postalCode string - The zip code or postal code.
region string - The state or region.
streetAddress string - The full street address component, which may include house number, street name, P.O. box, and multi-line extended street address information.
type string - A label indicating the function of the address. Examples: work, home
dateOfBirth string YYY-MM-DD The user's date of birth.
displayName string - The name of the user, suitable for display. This name should be the full name of the user.
emails object - Required Email addresses for the user. The value should be canonicalized by the service provider.
dateAdded string - The date and time the email was added to the user's profile.
dateVerified string - The date and time the email was verified.
notifications boolean true/false If true, user has opted in for notification emails.
type string - A label indicating the attribute's function. Example: Work, home
value string - Required Email address value.
verified boolean true/false If true, an email has been verified by the user.
emergencyContacts object - Emergency Contact information for the user.
country string - A two-letter country code defined in ISO 3166-1 alpha-2 of the emergency contact.
emails string - Emails of the emergency contact.
locality string - The city or locality of the emergency contact.
name string - Name of the emergency contact.
phones string - Phone numbers of the emergency contact.
postalCode string - The zip code or postal code of the emergency contact.
region string - The state or region of the emergency contact.
relationship string - Required Emergency contact relationship. Supported values: Spouse, Brother, Sister, Parent, Life Partner, Other
streetAddress string - The full street address component of the emergency contact, which may include house number, street name, P.O. box, and multi-line extended street address information.
entitlements string - The features enabled for the user.
externalId string - User identifier from the provisioning user.
gender string - The user's gender. Supported values: Male, Female, Others
id string UUID Required Unique identifier for the user.
localeOverrides object - Support for users who want to override locale settings.
preference24Hour string - Preferred 24 hour format for the user. Supported values: h:mm AM/PM, H:mm
preferenceCurrencySymbolLocation string - Preferred currency symbol location for the user. Supported values: BeforeAmount, AfterAmount
preferenceDateFormat string - Preferred date format for the user. Supported values: mm/dd/yyyy, mm.dd.yyyy, mm-dd-yyyy, dd/mm/yyyy, dd.mm.yyyy, dd-mm-yyyy, yyyy/mm/dd, yyyy.mm.dd, yyyy-mm-dd
preferenceDefaultCalView string - Preferred default calendar view for the user. Supported values: day, week, month
preferenceDistance string - Preferred distance metric. Supported values: mile, km
preferenceEndDayViewHour integer - Preferred hour setting for the end of day. Supported values: 0-23
preferenceFirstDayOfWeek string - Preferred first day of the week for the user.
preferenceHourMinuteSeparator string - Preferred separator between hour and minute. Supported values: :, .
preferenceNegativeCurrencyFormat string - Preferred negative currency format for the user. Supported values: -100, (100)
preferenceNegativeNumberFormat string - Preferred negative number format for the user. Supported values: -100, (100)
preferenceNumberFormat string - Preferred number format for the user. Supported values: 1,000.00, 1.000,00, 1 000,00, 1'000.00, 1'000,00
preferenceStartDayViewHour integer - Preferred start of day for the user. Begins at 1.
meta object - -
name object - Required The user's name.
familyName string - Required The family or last name of the user.
formatted string - The full name, including all middle names, title, and suffixes as appropriate, formatted for display Example: Ms. Barbara J Jensen, III
givenName string - Required The given or first name of the user.
hasNoMiddleName boolean true/false If true, the user does not have a middle name.
honorificPrefix string - The honorific or title prefix(es) of the user.
honorificSuffix string - The honorific suffix(es) of the user.
legalName string - The legal name of the user.
middleInitial string - The middle initial of the user's middle name, if the user has a middle name.
middleName string - The middle name(s) of the user.
nickName string - The casual way to address the user.
phoneNumbers object - Phone numbers for the user.
countryCode string - A two-letter code defined in ISO 3166-1 alpha-2 denoting the country the phone number was issued in.
display string - A phone number for display.
notifications boolean true/false If true, the user has opted in for mobile device notifications.
operatingSystem string - The operating system of the device, when the phone is cellphone. Supported values: Android Phone, Android Tablet, Blackberry, iOS Phone, iOS Tablet, Not a smartphone, Other iOS device, Other smartphone, Unknown, Window Mobile
primary boolean true/false If true, this is the primary device for mobile devices.
type string - A label indicating the phones's function. Example: Work, Home
value string - Phone number value.
preferredLanguage string - Indicates the user's preferred written or spoken language. Used for selecting a localized user interface.
timezone string olson The user's time zone. Example: America/Los_Angeles
Payroll PayrollExtension - -
User EnterpriseUser - -
Approver SpendApprover - -
Delegate SpendDelegate - -
Role SpendRole - -
User SpendUser - -
UserPreference ExpenseUserPreferenceExtension - -
WorkflowPreference WorkflowPreferenceExtension - -
User TravelUser - -
userName string - Required The name that can be used to log in to CTE.

Travel User

Name Type Format Description
ruleClass complex - Required Defines the rule class for the travel user either ID or name should be provided.
travelNameRemark string - Travel name remark.
xmlProfileSyncId string - User-assigned Travel user identifier that allows the user profile to be synchronized with other vendors.
travelCrsName string - The name of the profile in the GDS system.
groups integer - List of user groups that user belongs to for certain permissions.
manager complex - Travel approver of this user.
customFields complex - User can set values to custom data fields.

Workflow Preference Extension

Name Type Format Description
emailAwaitApprovalOnCashAdvance boolean true/false If true, an email is sent when a cash advance is awaiting approval. Default: true
emailAwaitApprovalOnPayment boolean true/false If true, an email is sent when a payment is awaiting approval. Default: true
emailAwaitApprovalOnReport boolean true/false If true, an email is sent when a report is awaiting approval. Default: true
emailAwaitApprovalOnTravelRequest boolean true/false If true, an email is sent when a travel request is awaiting approval. Default: true
emailStatusChangeOnCashAdvance boolean true/false If true, an email is sent when the cash advance status changes. Default: true
emailStatusChangeOnPayment boolean true/false If true, an email is sent when the payment status changes. Default: true
emailStatusChangeOnReport boolean true/false If true, an email is sent when the report status changes. Default: true
emailStatusChangeOnTravelRequest boolean true/false If true, an email is sent when the travel request status changes. Default: true
promptForApproverOnPaymentSubmit boolean true/false If true, a prompt for approver is displayed when submitting a payment. Default: false
promptForApproverOnReportSubmit boolean true/false If true, a prompt for approver is displayed when submitting a report. Default: false
promptForApproverOnTravelRequestSubmit boolean true/false If true, a prompt for approver is displayed when submitting a travel request. Default: false

Bulk Request

Name Type Format Description
schemas string - -
Operations object - -
data User - -
method string - Supported values: POST, PUT, PATCH
path string - -

Spend User

Name Type Format Description
budgetCountryCode string Valid ISO 3166 country code for Budget.
country string - Required Valid ISO 3166 country code.
ledgerCode string - Ledger code to associate with the user.
locale string - Required Valid locale from the list of configured locales as defined in [RFC5646]. Example: en-US
reimbursementCurrency string - Required Valid three digit currency code in the list of system reimbursement currencies.
reimbursementType object - Required The reimbursement type for the user.
stateProvince string - Valid ISO sub country code. Example: WA

Spend Role

Name Type Format Description
roles object - Expense roles for the employee.
roleGroups object - Group(s) to be associated with the Expense role.
roleName object - Required Expense role for the employee.

Spend Delegate

Name Type Format Description
delegateProdCode object - A list of delegates associated with the delegate's product code.
canApprove boolean true/false If true, the delegate can approve.
canPrepare boolean true/false If true, the delegate can prepare.
canPrepareForApproval boolean true/false If true, the delegate can prepare for approval.
canReceiveApprovalEmail boolean true/false If true, the delegate can receive approval emails.
canReceiveEmail boolean true/false If true, the delegate can receive emails.
canSubmit boolean true/false If true, the delegate can submit.
canSubmitTravelRequest boolean true/false If true, the delegate can submit travel request.
canUseBi boolean true/false If true, the delegate can use BI.
canViewReceipt boolean true/false If true, the delegate can view receipts.
delegate object - Required User reference for the delegate.
$ref string - The URI reference for the user.
displayName string - The username for the user.
employeeNumber string - Required The employee number for the user.
value object - The internal UUID identifier for the user.
temporaryDelegatation object - Determines if delegate can temporarily approve.
temporaryDelegationFromDate string - Start date for delegate's temporary approval permissions.
temporaryDelegationToDate string - End date for delegate's temporary approval permissions.

Spend Approver

Name Type Format Description
approverType object - A list of approvers associated with the approver's type.
approver object - The user reference for the approver.
$ref string - The URI reference for the user.
displayName string - The username for the user.
employeeNumber string - Required The employee number for the user.
value object - The internal UUID identifier for the user.
primary boolean true/false Required If true, the associated user is the primary approver.

Enterprise User

Name Type Format Description
companyId string - Required The SAP Concur ID of the company.
costCenter string - Employee cost center for product.
department string - User supplied department name.
division string - User supplied division name.
employeeNumber string - User supplied employee's number within the company, unique for the company.
jobTitle string - User's job title in the company.
manager object - The manager of the user.
$ref string - The URI of the SCIM resource representing the referenced user.
displayName string - The referenced user's display name.
employeeNumber string - The referenced user's employee number, if it is an Enterprise user.
value string - The referenced user's UUID.
orgUnit string - User supplied org unit name.
organization string - Company name.
self object - A reference to the user.
$ref string - The URI of the SCIM resource representing the referenced user.
startDate string YYYY-MM-DD Start date.
terminationDate string YYYY-MM-DD Termination date. If the employee is terminated, this can also be used to calculate the data retention period.

Expense User Preference Extension

Name Type Format Description
allowCreditCardTransArrivalEmails boolean true/false If true, allows credit card transaction arrival notification emails. Default: true
allowReceiptImageAvailEmails boolean true/false If true, sends an email when faxed receipts are successfully received. Default: true
autoAddTripCardTransOnReport boolean true/false If true, adds company card transactions within trip dates to one (1) click expense report.
defaultReportPrintFormat string - Default expense report print type. Supported values: RECEIPTS. DETAILED, FAX
expenseAuditRequired string - Expense audit is required. Supported values: NEVER, REQUIRED, ALWAYS
processorReportAccess string - Report access for processor roles. Supported values: Expense Processor, Expense Processor Audit, Expense Processor Manager
promptForCardTransactionsOnReport boolean true/false If true, displays a prompt for company card transactions when creating a new report. Default: true
promptForReportPrintFormat boolean true/false If true, displays a prompt for the report format before printing.
showExpenseOnReport string - Show expenses on detailed report.
showImagingIntro boolean true/false If true, displays imaging introduction. Default: true
showInstructHelpPanel boolean true/false If true, displays instructional help. Default: true
showTotalOnReport boolean true/false If true, displays report totals on detailed report. Supported values: ALL, PARENT, NOTHING
useQuickItinAsDefault boolean true/false If true, uses quick itinerary as default.

Payroll Extension

Name Type Format Description
adp object - ADP settings for employee.
companyCode string - Required The company code for the employee within ADP.
deductionCode string - Required The deduction code for the employee within ADP.
employeeFileNumber string - Required The identifier for the employee within ADP, also known as the Employee File Number.

Provision Status

Name Type Format Description
id string UUID Required Unique identifier for the provisioning request.
operations object - The status of each operation of the provisioning request.
extensions object - The extensions' status.
messages object - Additional messages in case of errors/warnings.
code string - Required Message code.
message string - The message description.
schemaPath string - Relative schema path of attribute.
type string - Required Message type. Supported values: error, warning, user
name string - Required Extension name.
status object - Required Status of the operation.
code string - HTTP status code.
completed boolean true/false Required If true, the processing extension is complete.
result string - The current processing status.
success boolean true/false If true, the processing extension was successful.
id string - Required Identifier of the operation.
resource object - Resource details.
id string UUID Unique identifier of the resource.
type string - Resource type.
status object - Required Status of the operation.
completed boolean true/false Required If true, the provisioning is complete.
success boolean true/false If true, the provisioning is successful.

Error

Name Type Format Description
messages object - Additional messages in case of errors/warnings.
code string - Required Message code.
message string - Message description.
schemaPath string - Relative schema path of attribute.
type string - Required Message type.

Definitions

Name Type Format Description
dateTime string - DateTime of where the transaction happened in format specified in ISO 8601, using UTC + Offset. For example, 2016-04-22T12:20+0700 (12:20 PM in Pacific Time).

Name of Release Note

Information First Published Information Last Modified Feature Target Release Date
March 2021 - June 2021
Any changes since the previous monthly release are highlighted in yellow in this release note.

Overview

The User Provisioning Service allows clients and partners to create, update, replace/delete (CRUD) Concur users using the new "User Provisioning Service. Once a user is provisioned, the user identity is setup in Profile, Travel and Spend.

For more information, please see User Provisioning API documentation

Business Purpose / Client Benefit

The user provisioning service allows clients & partners to provision users faster and with increased access to user data attributes.

Configuration / Feature Activation

The feature is available with web services and configuration is required to use it.

Spend User Provisioning

Important: This API is currently in pre-release status and is only available to approved early access participants. The API is under development and might change before being generally released. To become an early access participant, contact your SAP Concur Representative.

Spend User Provisioning allows callers to provision a user in the SAP Concur spend domain. This is an asynchronous downstream process from the User Provisioning v4 service. Currently spend user data can be created, modified, and replaced with the POST, PATCH, and PUT provisioning operations.

Limitations: This API is only available to partners who have been granted access. Access to this documentation does not provide access to the API.

Spend User Provisioning

Provisioning a New Spend Resource

Creates one or more provisioning request containing spend relevant data using the /provision/v4/Bulk endpoint. This section discusses the spend extensions and how to use them in tandem with the core extensions to provision a user with spend data. In order to create a user within the SAP Concur interface, the provision request must contain the information required to also provision the core user. The Spend User extension is the required foundation on which the other spend extensions depend. Without a successful Spend User save, the other spend extensions cannot succeed.

POST is used to create a new resource.

Scopes

spend.user.general.writeonly - Refer to Scope Usage for full details.

Request

URI

Template
POST https://www.us.api.concursolutions.com/provisioning/v4/Bulk/
Parameters

None.

Payload

Response

Status Codes

Headers

Payload

Examples

Request

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:BulkRequest"
    ],
    "failOnErrors": 1,
    "Operations": [
        {
            "method": "POST",
            "path": "/Users",
            "bulkId": "bulk-operation-1",
            "data": {
                "userName": "Chris.doe198@sap.com",
                "active": true,
                "name": {
                    "formatted": "Chris Doe",
                    "legalName": "Chris Doe",
                    "familyName": "Doe",
                    "givenName": "Chris"
                },
                "emails": [
                    {
                        "value": "Chris.doe198@sap.com",
                        "type": "Work"
                    }
                ],
                "entitlements": [
                    "Expense"
                ],
                "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
                    "employeeNumber": "3749",
                    "companyId": "xxxxxxxx-xxx-xxx-xxx-9300b1c317xxx"
                },
                "urn:ietf:params:scim:schemas:extension:spend:2.0:User": {
                    "reimbursementCurrency": "USD",
                    "reimbursementType": "CONCUR_PAY",
                    "ledgerCode": "DEFAULT",
                    "country": "US",
                    "stateProvince": "WA",
                    "locale": "en-US",
                    "customData": [
                        {
                            "id": "custom1",
                            "value": "testing"
                        },
                        {
                            "id": "custom2",
                            "value": "tested"
                        },
                        {
                            "id": "orgUnit1",
                            "value": "testDepartment"
                        },
                        {
                            "id": "orgUnit2",
                            "value": "testSquadAlpha"
                        }
                    ]
                },
                "urn:ietf:params:scim:schemas:extension:spend:2.0:Approver": {
                    "request": [
                        {
                        "approver": {
                            "employeeNumber": "requestApprover"
                        },
                        "primary": true
                        }
                    ],
                    "report": [
                        {
                        "approver": {
                            "employeeNumber": "reportApprover"
                        },
                        "primary": false
                        }
                    ]
                },
                "urn:ietf:params:scim:schemas:extension:spend:2.0:Delegate": {
                    "expense": [
                        {
                            "canApprove": true,
                            "canPrepare": true,
                            "canPrepareForApproval": true,
                            "canReceiveApprovalEmail": true,
                            "canReceiveEmail": true,
                            "canSubmit": true,
                            "canSubmitTravelRequest": true,
                            "canUseBi": true,
                            "canViewReceipt": true,
                            "delegate": {
                                "employeeNumber": "expenseDelegate"
                            },
                            "temporaryDelegatation": {
                                "temporaryDelegationFromDate": "2020-02-19T03:15:00.000Z",
                                "temporaryDelegationToDate": "2020-02-19T03:59:00.000Z"
                            }
                        },
                        {
                            "canApprove": true,
                            "canPrepare": true,
                            "canPrepareForApproval": true,
                            "canReceiveApprovalEmail": true,
                            "canReceiveEmail": true,
                            "canSubmit": true,
                            "canSubmitTravelRequest": true,
                            "canUseBi": true,
                            "canViewReceipt": true,
                            "delegate": {
                                "employeeNumber": "expenseDelegate"
                            },
                            "temporaryDelegatation": {
                                "temporaryDelegationFromDate": "2020-02-19T03:15:00.000Z",
                                "temporaryDelegationToDate": "2020-02-19T03:59:00.000Z"
                            }
                        }
                    ]
                },
                "urn:ietf:params:scim:schemas:extension:spend:2.0:Role": {
                    "roles": [
                        {
                            "roleName": "EXP_USER",
                            "roleGroups": ["R&D-Dev-Exp", "R&D-QA-Exp"]
                        }
                    ]
                },
                "urn:ietf:params:scim:schemas:extension:spend:2.0:WorkflowPreference": {
                    "emailStatusChangeOnCashAdvance": true,
                    "emailAwaitApprovalOnCashAdvance": true,
                    "emailStatusChangeOnReport": true,
                    "emailAwaitApprovalOnReport": true,
                    "promptForApproverOnReportSubmit": true,
                    "emailStatusChangeOnTravelRequest": true,
                    "emailAwaitApprovalOnTravelRequest": true,
                    "promptForApproverOnTravelRequestSubmit": true,
                    "emailStatusChangeOnPayment": true,
                    "emailAwaitApprovalOnPayment": true,
                    "promptForApproverOnPaymentSubmit": true
                },
                "urn:ietf:params:scim:schemas:extension:spend:2.0:UserPreference": {
                    "allowCreditCardTransArrivalEmails": true,
                    "allowReceiptImageAvailEmails": true,
                    "promptForCardTransactionsOnReport": true,
                    "autoAddTripCardTransOnReport": true,
                    "promptForReportPrintFormat": true,
                    "defaultReportPrintFormat": "DETAILED",
                    "showTotalOnReport": true,
                    "showExpenseOnReport": "ALL",
                    "showInstructHelpPanel": true,
                    "showImagingIntro": true,
                    "expenseAuditRequired": "REQUIRED",
                    "useQuickItinAsDefault": true
                },
                "urn:ietf:params:scim:schemas:extension:enterprise:2.0:Payroll": {
                    "adp": {
                        "companyCode": "companyCode",
                        "deductionCode": "HLTH",
                        "employeeFileNumber": "1234"
                    }
                }
            }
        }
    ]
}

Updating Existing Spend User Resources

Creates one or more provision requests using the provision/v4/Bulk endpoint to patch existing spend user resources.

PATCH requests modify the resource.

Scopes

spend.user.general.writeonly - Refer to Scope Usage for full details.

Request

URI

Template
POST https://www.us.api.concursolutions.com/provisioning/v4/Bulk/
Parameters

None.

Headers

Payload

Response

Status Codes

Headers

Payload

Examples

Request

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:BulkRequest",
        "urn:ietf:params:scim:api:messages:2.0:PatchOp"
    ],
    "failOnErrors": 1,
    "Operations": [
        {
            "method": "PATCH",
            "path": "/Users/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
            "data": {
                "Operations": [
                    {
                        "op": "replace",
                        "path": "urn:ietf:params:scim:schemas:extension:spend:2.0:User:country",
                        "value": "US"
                    },
                    {
                        "op": "add",
                        "value": {
                            "urn:ietf:params:scim:schemas:extension:spend:2.0:User": {
                                "locale": "es-419",
                                "reimbursementType": "PAY_PAL",
                                "customData": [
                                    {
                                        "id": "custom1",
                                        "value": "patchChangeCustom1"
                                    },
                                    {
                                        "id": "custom8",
                                        "value": "newCustomObject"
                                    }
                                ]
                            }
                        }
                    },
                    {
                        "op": "add",
                        "value": {
                            "urn:ietf:params:scim:schemas:extension:spend:2.0:Approver": {
                                "budget": [
                                    {
                                        "approver": {
                                            "value": "aaaaaaaa-bbbb-cccc-aaaa-bbbbbbbbbbb3",
                                            "displayName": "TestApprover@test.com",
                                            "employeeNumber": "100001",
                                            "$ref": "http://www.test.com/users/100001"
                                        },
                                        "primary": true
                                    }
                                ]
                            }
                        }
                    }
                ]
            }
        }
    ]
}

Replacing Existing Spend User Resources

Creates one or more provision requests using the /Bulk endpoint to replaces existing spend user resources.

PUT is used to replace an existing resource.

Scopes

spend.user.general.writeonly - Refer to Scope Usage for full details.

Request

URI

Template
POST https://www.us.api.concursolutions.com/provisioning/v4/Bulk/
Parameters

None.

Headers

Payload

Response

Status Codes

Headers

Payload

Examples

Request

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:BulkRequest"
    ],
    "failOnErrors": 1,
    "Operations": [
        {
            "method": "PUT",
            "path": "/Users/aaaaaaaa-bbbb-cccc-aaaa-bbbbbbbbbbb1",
            "bulkId": "Seattle",
            "data": {
                "id": "aaaaaaaa-bbbb-cccc-aaaa-bbbbbbbbbbb1",
                "userName": "john.doe21224@sap.com",
                "active": false,
                "name": {
                    "formatted": "Mr. John Doe",
                    "legalName": "Mr. John Doe",
                    "middleName": "Joe",
                    "middleInitial": "J",
                    "familyName": "Doe",
                    "givenName": "John",
                    "honorificPrefix": "Prof Dr Mr",
                    "honorificSuffix": "VI",
                    "hasNoMiddleName": true
                },
                "emails": [
                    {
                        "value": "john.doe193@sap.com",
                        "type": "work"
                    }
                ],
                "entitlements": [
                    "Expense"
                ],
                "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
                    "employeeNumber": "3749",
                    "companyId": "xxxxxxxx-xxx-xxx-xxx-9300b1c317xxx"
                },
                "urn:ietf:params:scim:schemas:extension:spend:2.0:User": {
                    "reimbursementCurrency": "USD",
                    "reimbursementType": "CONCUR_PAY",
                    "ledgerCode": "DEFAULT",
                    "country": "US",
                    "budgetCountryCode": "US",
                    "stateProvince": "WA",
                    "locale": "en-US",
                    "customData": [
                        {
                            "id": "custom1",
                            "value": "testing"
                        },
                        {
                            "id": "orgUnit2",
                            "value": "testSquadAlpha"
                        }
                    ]
                },
                "urn:ietf:params:scim:schemas:extension:spend:2.0:Approver": {
                    "request": [
                        {
                        "approver": {
                            "employeeNumber": "requestApprover"
                        },
                        "primary": true
                        }
                    ],
                },
            }
        }
    ]
}

Schema

Spend User

Name Type Format Description
reimbursementCurrency string - Required Valid three digit currency code in the list of system reimbursement currencies.
reimbursementType object - Required The reimbursement type for the user. Supported values: ACCOUNTS_PAYABLE, ADP_PAYROLL, CONCUR_PAY, PAY_PAL, OTHER
ledgerCode string - Ledger code to associate with the user.
country string - Required Valid ISO 3166 country code.
budgetCountryCode string - Valid ISO 3166 country code for Budget.
stateProvince string - Valid ISO sub country code. Example: WA
locale string - Required Valid locale from the list of configured locales as defined in [RFC5646]. Example: en-US
cashAdvanceAccountCode string - Valid cash advance account code.
testEmployee boolean true/false A Boolean value indicating whether the user is a test user. Can't be modified after the user is created. Can only be set at creation.
nonEmployee boolean true/false A Boolean value indicating whether the user is a non-employee.
biManager UserReference - The UUID of the Reporting Manager.
customData CustomData - The Custom Data associated with this user.

ADP Extension

Name Type Format Description
adp ADP - ADP settings for employee.

Approver Extension

Name Type Format Description
report SpendApprover - A user's report approvers.
cashAdvance SpendApprover - A user's cash advance approvers.
request SpendApprover - A user's request approvers.
invoice SpendApprover - A user's invoice approvers.
purchaseRequest SpendApprover - A user's purchase request approvers.
statement SpendApprover - A user's statement approvers.
budget SpendApprover - A user's budget approvers.

Delegate Extension

Name Type Format Description
expense SpendDelegate - The user's expense delegates.
payment SpendDelegate - The user's payment delegates.
purchaseRequest SpendDelegate - The user's purchase request delegates.

Spend Role

Name Type Format Description
roles Role - Expense roles for employee.

User Preference Extension

Name Type Format Description
showImagingIntro boolean true/false If true, displays imaging introduction. Default: true
expenseAuditRequired string - Expense audit is required. Supported values: NEVER, REQUIRED, ALWAYS
allowCreditCardTransArrivalEmails boolean true/false If true, allows credit card transaction arrival notification emails. Default: true
allowReceiptImageAvailEmails boolean true/false If true, allows credit card transaction arrival notification emails. Default: true
promptForCardTransactionsOnReport boolean true/false If true, displays a prompt for company card transactions when creating a new report. Default: true
autoAddTripCardTransOnReport boolean true/false If true, adds company card transactions within trip dates to one (1) click expense report.
promptForReportPrintFormat boolean true/false If true, displays a prompt for the report format before printing.
defaultReportPrintFormat string - Default expense report print type. Supported values: RECEIPTS. DETAILED, FAX
showTotalOnReport boolean true/false If true, displays report totals on detailed report.
showExpenseOnReport string - Show expenses on detailed report. Supported values: ALL, PARENT, NOTHING
showInstructHelpPanel boolean true/false If true, displays instructional help. Default: true
useQuickItinAsDefault boolean true/false If true, uses quick itinerary as default.

Workflow Preferences Extension

Name Type Format Description
emailStatusChangeOnCashAdvance boolean true/false If true, an email is sent when the cash advance status changes. Default: true
emailAwaitApprovalOnCashAdvance boolean true/false If true, an email is sent when a cash advance is awaiting approval. Default: true
emailStatusChangeOnReport boolean true/false If true, an email is sent when the report status changes. Default: true
emailAwaitApprovalOnReport boolean true/false If true, an email is sent when a report is awaiting approval. Default: true
promptForApproverOnReportSubmit boolean true/false If true, a prompt for approver is displayed when submitting a report. Default: false
emailStatusChangeOnTravelRequest boolean true/false If true, an email is sent when the travel request status changes. Default: true
emailAwaitApprovalOnTravelRequest boolean true/false If true, an email is sent when a travel request is awaiting approval. Default: true
promptForApproverOnTravelRequestSubmit boolean true/false If true, a prompt for approver is displayed when submitting a travel request. Default: false
emailStatusChangeOnPayment boolean true/false If true, an email is sent when the payment status changes. Default: true
emailAwaitApprovalOnPayment boolean true/false If true, an email is sent when a payment is awaiting approval. Default: true
promptForApproverOnPaymentSubmit boolean true/false If true, a prompt for approver is displayed when submitting a payment. Default: false

User Reference

Name Type Format Description
value string uuid The internal UUID identifier for the user.
displayName string - The username for the user.
employeeNumber string - The employee number for the user.
$ref string uri The URI reference for the user.

Custom Data

Name Type Format Description
id string - custom1 - custom22, orgUnit1 - orgUnit6
value string - Value of the custom field. For list = List Item Code.

ADP

Name Type Format Description
companyCode string - Required The company code for the employee within ADP.
deductionCode string - Required The deduction code for the employee within ADP.
employeeFileNumber string - Required The identifier for the employee within ADP, also known as the Employee File Number.

Spend Approver

Name Type Format Description
approver UserReference - Required The UserReference of the approver.
primary boolean true/false If true, the associated user is primary approver.

Spend Delegate

Name Type Format Description
canApprove boolean true/false If true, the delegate can approve.
canPrepare boolean true/false If true, the delegate can prepare.
canPrepareForApproval boolean true/false If true, the delegate can prepare for approval.
canReceiveApprovalEmail boolean true/false If true, the delegate can receive approval emails.
canReceiveEmail boolean true/false If true, the delegate can receive emails.
canSubmit boolean true/false If true, the delegate can submit.
canSubmitTravelRequest boolean true/false If true, the delegate can submit travel requests.
canUseBi boolean true/false If true, the delegate can use BI.
canViewReceipt boolean true/false If true, the delegate can view receipts.
delegate UserReference - The UserReference to the delegate.
temporaryDelegation TemporaryDelegate - Determines if delegate can temporarily approve.

Temporary Delegate

Name Type Format Description
temporaryDelegationFromDate string - Start date for delegate's temporary approval permissions.
temporaryDelegationToDate string - End date for delegate's temporary approval permissions.

Role

Name Type Format Description
roleName string - Required Expense role for employee.
roleGroups string - Required Group(s) to be associated with the Expense role.

Spend User Retrieval

Important: This API is currently in pre-release status and is only available to approved early access participants. The API is under development and might change before being generally released. To become an early access participant, contact your SAP Concur Representative.

Limitations: This API is only available to partners who have been granted access. Access to this documentation does not provide access to the API.

Spend User Retrieval

Retrieving all Spend Users in a Company

Retrieves all the spend users for a given company. The result is paginated and can be filtered using the parameters listed below.

Scopes

spend.user.general.read - Refer to Scope Usage for full details.

Request

URI

Template
GET https://www.us.api.concursolutions.com/spend/v4/Users
Parameters
Name Type Format Description
startIndex integer startIndex >= 1 The starting index of the paginated result.
itemsPerPage integer 100 >= itemsPerPage >= 1 The number of user resources to return on a single page.
filter string ABNF compliant The SCIM compliant filter string to be used when retrieving user resources.

Note: Not all aspects of SCIM filtering are supported. The following fields are implemented with the corresponding set of operators:

Headers

Payload

None.

Response

Headers

Payload

Status Codes

Examples

Request

GET https://www.us.api.concursolutions.com/provisioning/v4/Users?&startIndex=1&itemsPerPage=4&filter=urn:ietf:params:scim:schemas:extension:spend:2.0:User:country+eq+%22US%22

Response

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "totalResults": 10000,
    "Resources": [
        {
            "schemas": [
                "urn:ietf:params:scim:schemas:extension:spend:2.0:Role",
                "urn:ietf:params:scim:schemas:extension:spend:2.0:WorkflowPreference",
                "urn:ietf:params:scim:schemas:extension:spend:2.0:User",
                "urn:ietf:params:scim:schemas:extension:enterprise:2.0:Payroll",
                "urn:ietf:params:scim:schemas:extension:spend:2.0:UserPreference",
                "urn:ietf:params:scim:schemas:extension:spend:2.0:Approver",
                "urn:ietf:params:scim:schemas:extension:spend:2.0:Delegate",
                "urn:ietf:params:scim:schemas:ScimResource"
            ],
            "id": "aaaaaaaa-xxxx-zzzz-xxxx-xxxxxxxxxxxx",
            "urn:ietf:params:scim:schemas:extension:spend:2.0:Role": {
                "roles": [
                    {
                        "roleName": "TRAVEL_USER"
                    }
                ]
            },
            "urn:ietf:params:scim:schemas:extension:spend:2.0:WorkflowPreference": {
                "emailStatusChangeOnCashAdvance": false,
                "emailAwaitApprovalOnCashAdvance": false,
                "emailStatusChangeOnReport": false,
                "emailAwaitApprovalOnReport": false,
                "promptForApproverOnReportSubmit": false,
                "emailStatusChangeOnTravelRequest": false,
                "emailAwaitApprovalOnTravelRequest": false,
                "promptForApproverOnTravelRequestSubmit": false,
                "emailStatusChangeOnPayment": false,
                "emailAwaitApprovalOnPayment": false,
                "promptForApproverOnPaymentSubmit": false
            },
            "urn:ietf:params:scim:schemas:extension:spend:2.0:User": {
                "reimbursementCurrency": "USD",
                "reimbursementType": "CONCUR_PAY",
                "country": "US",
                "locale": "en-US",
                "testEmployee": false,
                "nonEmployee": false,
                "customData": []
            },
            "urn:ietf:params:scim:schemas:extension:enterprise:2.0:Payroll": {
                "adp": {}
            },
            "urn:ietf:params:scim:schemas:extension:spend:2.0:UserPreference": {
                "showImagingIntro": true,
                "expenseAuditRequired": "REQUIRED",
                "allowCreditCardTransArrivalEmails": true,
                "allowReceiptImageAvailEmails": true,
                "promptForCardTransactionsOnReport": true,
                "autoAddTripCardTransOnReport": true,
                "promptForReportPrintFormat": true,
                "defaultReportPrintFormat": "RECEIPTS",
                "showTotalOnReport": true,
                "showExpenseOnReport": "PARENT",
                "showInstructHelpPanel": true,
                "useQuickItinAsDefault": false
            },
            "urn:ietf:params:scim:schemas:extension:spend:2.0:Approver": {},
            "urn:ietf:params:scim:schemas:extension:spend:2.0:Delegate": {}
        }
    ],
    "startIndex": 1,
    "itemsPerPage": 1
}

Retrieving a Spend User

Retrieves a specific user's spend data.

Scopes

spend.user.general.read - Refer to Scope Usage for full details.

Request

URI

Template
GET https://www.us.api.concursolutions.com/spend/v4/Users/{uuid}
Parameters
Name Type Format Description
uuid string RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace The unique identifier for the user that should be retrieved.

Headers

Payload

None.

Response

Headers

Payload

Status Codes

Examples

Request

GET https://www.us.api.concursolutions.com/provisioning/v4/Users/aaaaaaaa-bbbb-cccc-aaaa-bbbbbbbbbbb1

Response

{
    "schemas": [
        "urn:com.concur.spend.user.model.scim.ScimResource",
        "urn:ietf:params:scim:schemas:extension:spend:2.0:Role",
        "urn:ietf:params:scim:schemas:extension:spend:2.0:WorkflowPreference",
        "urn:ietf:params:scim:schemas:extension:spend:2.0:User",
        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:Payroll",
        "urn:ietf:params:scim:schemas:extension:spend:2.0:UserPreference",
        "urn:ietf:params:scim:schemas:extension:spend:2.0:Delegate",
        "urn:ietf:params:scim:schemas:extension:spend:2.0:Approver"
    ],
    "id": "aaaaaaaa-bbbb-cccc-aaaa-bbbbbbbbbbb1",
    "urn:ietf:params:scim:schemas:extension:spend:2.0:Role": {
        "roles": [
            {
                "roleName": "REQ_USER"
            },
            {
                "roleName": "EXP_USER"
            }
        ]
    },
    "urn:ietf:params:scim:schemas:extension:spend:2.0:WorkflowPreference": {
        "emailStatusChangeOnCashAdvance": true,
        "emailAwaitApprovalOnCashAdvance": true,
        "emailStatusChangeOnReport": true,
        "emailAwaitApprovalOnReport": true,
        "promptForApproverOnReportSubmit": true,
        "emailStatusChangeOnTravelRequest": true,
        "emailAwaitApprovalOnTravelRequest": true,
        "promptForApproverOnTravelRequestSubmit": true,
        "emailStatusChangeOnPayment": true,
        "emailAwaitApprovalOnPayment": true,
        "promptForApproverOnPaymentSubmit": true
    },
    "urn:ietf:params:scim:schemas:extension:spend:2.0:User": {
        "reimbursementCurrency": "USD",
        "reimbursementType": "CONCUR_PAY",
        "ledgerCode": "DEFAULT",
        "country": "US",
        "stateProvince": "WA",
        "locale": "en-US",
        "testEmployee": false,
        "nonEmployee": false,
        "customData": [
            {
                "id": "custom20",
                "value": "testing"
            },
            {
                "id": "custom9",
                "value": "testing"
            },
            {
                "id": "orgunit3",
                "value": "testDepartment"
            }
        ]
    },
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:Payroll": {
        "adp": {}
    },
    "urn:ietf:params:scim:schemas:extension:spend:2.0:UserPreference": {
        "showImagingIntro": true,
        "expenseAuditRequired": "REQUIRED",
        "allowCreditCardTransArrivalEmails": true,
        "allowReceiptImageAvailEmails": true,
        "promptForCardTransactionsOnReport": true,
        "autoAddTripCardTransOnReport": true,
        "promptForReportPrintFormat": true,
        "defaultReportPrintFormat": "DETAILED",
        "showTotalOnReport": true,
        "showExpenseOnReport": "ALL",
        "showInstructHelpPanel": true,
        "useQuickItinAsDefault": true
    },
    "urn:ietf:params:scim:schemas:extension:spend:2.0:Delegate": {
        "expense": [
            {
                "canApprove": true,
                "canPrepare": true,
                "canPrepareForApproval": false,
                "canReceiveApprovalEmail": true,
                "canReceiveEmail": true,
                "canSubmit": true,
                "canSubmitTravelRequest": true,
                "canUseBi": false,
                "canViewReceipt": true,
                "delegate": {
                    "value": "aaaaaaaa-bbbb-cccc-aaaa-bbbbbbbbbbb2"
                }
            }
        ]
    },
    "urn:ietf:params:scim:schemas:extension:spend:2.0:Approver": {
        "request": [
            {
                "approver": {
                    "value": "aaaaaaaa-bbbb-cccc-aaaa-bbbbbbbbbbb2"
                },
                "primary": true
            }
        ],
        "report": [
            {
                "approver": {
                    "value": "aaaaaaaa-bbbb-cccc-aaaa-bbbbbbbbbbb2"
                },
                "primary": true
            }
        ]
    }
}

Schema

Spend User

Name Type Format Description
reimbursementCurrency string - Required Valid three digit currency code in the list of system reimbursement currencies.
reimbursementType object - Required The reimbursement type for the user. Supported values: ACCOUNTS_PAYABLE, ADP_PAYROLL, CONCUR_PAY, PAY_PAL, OTHER
ledgerCode string - Ledger code to associate with the user.
country string - Required Valid ISO 3166 country code.
budgetCountryCode string - Valid ISO 3166 country code for Budget.
stateProvince string - Valid ISO sub country code. Example: WA
locale string - Required Valid locale from the list of configured locales as defined in [RFC5646]. Example: en-US
cashAdvanceAccountCode string - Valid cash advance account code.
testEmployee boolean true/false A Boolean value indicating whether the user is a test user. Can't be modified after the user is created. Can only be set at creation.
nonEmployee boolean true/false A Boolean value indicating whether the user is a non-employee.
biManager UserReference - The UUID of the Reporting Manager.
customData CustomData - The Custom Data associated with this user.

ADP Extension

Name Type Format Description
adp ADP - ADP settings for employee.

Approver Extension

Name Type Format Description
report SpendApprover - A user's report approvers.
cashAdvance SpendApprover - A user's cash advance approvers.
request SpendApprover - A user's request approvers.
invoice SpendApprover - A user's invoice approvers.
purchaseRequest SpendApprover - A user's purchase request approvers.
statement SpendApprover - A user's statement approvers.
budget SpendApprover - A user's budget approvers.

Delegate Extension

Name Type Format Description
expense SpendDelegate - The user's expense delegates.
payment SpendDelegate - The user's payment delegates.
purchaseRequest SpendDelegate - The user's purchase request delegates.

Spend Role

Name Type Format Description
roles Role - Expense roles for employee.

User Preference Extension

Name Type Format Description
showImagingIntro boolean true/false If true, displays imaging introduction. Default: true
expenseAuditRequired string - Expense audit is required. Supported values: NEVER, REQUIRED, ALWAYS
allowCreditCardTransArrivalEmails boolean true/false If true, allows credit card transaction arrival notification emails. Default: true
allowReceiptImageAvailEmails boolean true/false If true, allows credit card transaction arrival notification emails. Default: true
promptForCardTransactionsOnReport boolean true/false If true, displays a prompt for company card transactions when creating a new report. Default: true
autoAddTripCardTransOnReport boolean true/false If true, adds company card transactions within trip dates to one (1) click expense report.
promptForReportPrintFormat boolean true/false If true, displays a prompt for the report format before printing.
defaultReportPrintFormat string - Default expense report print type. Supported values: RECEIPTS. DETAILED, FAX
showTotalOnReport boolean true/false If true, displays report totals on detailed report.
showExpenseOnReport string - Show expenses on detailed report. Supported values: ALL, PARENT, NOTHING
showInstructHelpPanel boolean true/false If true, displays instructional help. Default: true
useQuickItinAsDefault boolean true/false If true, uses quick itinerary as default.

Workflow Preferences Extension

Name Type Format Description
emailStatusChangeOnCashAdvance boolean true/false If true, an email is sent when the cash advance status changes. Default: true
emailAwaitApprovalOnCashAdvance boolean true/false If true, an email is sent when a cash advance is awaiting approval. Default: true
emailStatusChangeOnReport boolean true/false If true, an email is sent when the report status changes. Default: true
emailAwaitApprovalOnReport boolean true/false If true, an email is sent when a report is awaiting approval. Default: true
promptForApproverOnReportSubmit boolean true/false If true, a prompt for approver is displayed when submitting a report. Default: false
emailStatusChangeOnTravelRequest boolean true/false If true, an email is sent when the travel request status changes. Default: true
emailAwaitApprovalOnTravelRequest boolean true/false If true, an email is sent when a travel request is awaiting approval. Default: true
promptForApproverOnTravelRequestSubmit boolean true/false If true, a prompt for approver is displayed when submitting a travel request. Default: false
emailStatusChangeOnPayment boolean true/false If true, an email is sent when the payment status changes. Default: true
emailAwaitApprovalOnPayment boolean true/false If true, an email is sent when a payment is awaiting approval. Default: true
promptForApproverOnPaymentSubmit boolean true/false If true, a prompt for approver is displayed when submitting a payment. Default: false

User Reference

Name Type Format Description
value string uuid The internal UUID identifier for the user.
displayName string - The username for the user.
employeeNumber string - The employee number for the user.
$ref string uri The URI reference for the user.

Custom Data

Name Type Format Description
id string - custom1 - custom22, orgUnit1 - orgUnit6
value string - Value of the custom field. For list = List Item Code.

ADP

Name Type Format Description
companyCode string - Required The company code for the employee within ADP.
deductionCode string - Required The deduction code for the employee within ADP.
employeeFileNumber string - Required The identifier for the employee within ADP, also known as the Employee File Number.

Spend Approver

Name Type Format Description
approver UserReference - Required The UserReference of the approver.
primary boolean true/false If true, the associated user is primary approver.

Spend Delegate

Name Type Format Description
canApprove boolean true/false If true, the delegate can approve.
canPrepare boolean true/false If true, the delegate can prepare.
canPrepareForApproval boolean true/false If true, the delegate can prepare for approval.
canReceiveApprovalEmail boolean true/false If true, the delegate can receive approval emails.
canReceiveEmail boolean true/false If true, the delegate can receive emails.
canSubmit boolean true/false If true, the delegate can submit.
canSubmitTravelRequest boolean true/false If true, the delegate can submit travel requests.
canUseBi boolean true/false If true, the delegate can use BI.
canViewReceipt boolean true/false If true, the delegate can view receipts.
delegate UserReference - The UserReference to the delegate.
temporaryDelegation TemporaryDelegate - Determines if delegate can temporarily approve.

Temporary Delegate

Name Type Format Description
temporaryDelegationFromDate string - Start date for delegate's temporary approval permissions.
temporaryDelegationToDate string - End date for delegate's temporary approval permissions.

Role

Name Type Format Description
roleName string - Required Expense role for employee.
roleGroups string - Required Group(s) to be associated with the Expense role.

List Response

Name Type Format Description
schemas string - The schemas present in the resource.
totalResults integer int32 Required The total number of results returned by the list or query operation.
Resources FullSpendUser - A multi-valued list of complex objects containing the requested resources.
startIndex integer int32 The 1-based index of the first result in the current set of list results.
itemsPerPage integer int32 The number of resources returned in a list response page.

Full Spend User

Name Type Format Description
schemas string - The schemas present in the resource.
urn:ietf:params:scim:schemas:extension:spend:2.0:Approver ApproverExtension - The user's spend approver data.
urn:ietf:params:scim:schemas:extension:spend:2.0:Delegate DelegateExtension - The user's spend delegate data.
urn:ietf:params:scim:schemas:extension:spend:2.0:Role SpendRole - The user's spend role data.
urn:ietf:params:scim:schemas:extension:spend:2.0:UserPreference UserPreferenceExtension - The user's user preference settings.
urn:ietf:params:scim:schemas:extension:enterprise:2.0:Payroll ADPExtension - The user's ADP data.
urn:ietf:params:scim:schemas:extension:spend:2.0:WorkflowPreference WorkflowPreferenceExtension - The user's workflow preference settings.

Error Message Response

Name Type Format Description
schemas string - The schemas present in this resource.
scimType string - A SCIM detailed error keyword.
detail string - A detailed, human readable message.
status integer int32 The HTTP status code.

Spend Role Codes

Important: This API is currently in pre-release status and is only available to approved early access participants. The API is under development and might change before being generally released. To become an early access participant, contact your SAP Concur Representative.

Column Description

Role Code Role Full Name Description Group-Aware Product Area
The role code value that can be used for provisioning with the Spend Role Extension. The full name of the role. The usage of the role. When assigning this role, one or more groups must be given. Shared with two or more SAP Concur products.

Expense Product Roles

Role Code Role Full Name Description Group-Aware Product Area
SHD_APP_CENTER_ADMIN App Center Listing Administrator The user assigned this role can submit App Center listings. This role is only assigned by SAP Concur to certain App Center partners. N Y
EXP_ATTENDEE_ADMIN Attendee Administrator The user assigned this role can view, modify, and activate or inactivate any attendee record in the system. Y Y
EXP_ATTENDEE_ADMIN_RO Attendee Administrator (Read only) The user assigned this role is considered a read-only auditor. The user can access and view but not modify and activate or inactivate an attendee record in the system. Y Y
SHD_AUTHORIZED_APPROVER Authorized Approver This is special approver role. The user assigned this role can approve, with a specified limit, specific expense reports. N N
N/A Account Code Administrator NOTE: This field is not supported. N N
EXP_AUTH_REQUEST_ADMIN Authorization Request Administrator The user assigned this role can view and update authorization requests in Authorization Administrator. Y N
EXP_AUTH_REQUEST_APPROVER Authorization Request Approver The user assigned this role can approve authorization requests in Expense Reports. N N
SHD_BILLING_ATTRIBUTES_USER Billing Attributes User The user assigned this role can manage billing related settings for the entity. N Y
SHD_BUDGET_ADMIN Budget Administrator For Budget Insight (Legacy): The user assigned this role can set budget amounts and assign budget approvers.
For Budget: The user assigned this role can configure the Fiscal Calendar, Budget Categories, Budget Tracking Fields, Budget Items, and Budget Settings.
The Budget Administrator can see the budget amounts as configured in the Budget Items, but not the budget actuals as is shown in the dashboards. Budget Administrators have access to all budget items within an entity.
N Y
SHD_BUDGET_APPROVER Budget Approver/Manager For Budget Insight (Legacy): The user assigned this role can review and approve expense reports using real-time budget figures.
For Budget: The user assigned this role can approve invoices, purchase requests, and expense reports and can view budgets in the budget dashboards.
The Budget Approver does not have access to the budget configuration information.
N Y
SHD_BUDGET_OWNER Budget Owner The user assigned this role owns the budget and can view budgets in the dashboards. The Budget Owner does not have access to the budget configuration information. N Y
SHD_BUDGET_VIEWER Budget Viewer The user assigned this role views budgets in the dashboards. There can be one or several budget viewers. The Budget Viewer does not have access to the budget configuration information. N Y
EXP_PCARD_ADMIN Card Program Administrator The user assigned this role manages the company's purchase card program and statement periods. Y N
EXP_PROCESSOR_CR Central Reconciliation Processor The user assigned this role processes (matches) invoice transactions associated with requests generated within the Request product. Y N
TRAVEL_USER Cliqbook User The user assigned this role can integrate with Cliqbook service. N N
EXP_CONFIG_ADMIN_CLIENT Client Expense Administrator This custom role is not available to all clients; availability is based on the client configuration. This field combines permissions from the Expense Configuration Administrator role and the Shared Configuration Administrator. The user assigned this role can access these options (some may allow add/edit; some may be view-only): Accounting administration, audit rules, car configuration, email reminders, exceptions, expense types, locations, policies, travel allowance, workflows. Y N
STATEMENT_APPROVER Company Bill Statement Approver The user assigned this role approves statement reports. This user must also be assigned the Expense Approver role. N N
STATEMENT_PROCESSOR Company Bill Statement Processor The user assigned this role views and updates statement reports in Expense Processor. This user must also be assigned the Expense Processor role. Y N
STATEMENT_PROCESSOR_AUDITOR Company Bill Statement Processor (Audit) The user assigned this role views statement reports in Expense Processor in read-only format. This user must also be assigned the Expense Processor (Audit) role. N -
STATEMENT_PROCESSOR_ADMIN Company Bill Statement Processor Manager The user assigned this role views, updates, and deletes statement reports in Expense Processor. This user must also be assigned the Expense Processor Manager role. Y N
STATEMENT_USER Company Bill Statement User The user assigned this role reviews and submits the purchasing card transactions in the statement reports. This user must also be assigned the Expense User role. N N
SHD_COMPANY_INFO_ADMIN Company Info Administrator The user assigned this role can update the Company Info section of the home page. N Y
N/A Concur Mobile User NOTE: This field is not supported. N N/A
SHD_COST_OBJECT_APPROVER Cost Object Approver This is special approver role, which is not assigned the same way as other roles. N N
SHD_DATA_RETENTION_ADMIN Data Retention Administrator The user assigned this role views and configures the data retention policy for the company and can hold and purge individual users. N Y
N/A Digital Compliance Administrator NOTE: This field is not supported. N N
SHD_EMPLOYEE_ADMIN Employee Administrator The user assigned this role can add and manage employees, including assigning roles, delegates, and preferences. The user can only assign the basic user roles (Expense User, Travel User), using the check boxes on the User Details page. They may also view and optionally edit and register cars on behalf of a user. Y Y
SHD_EMPLOYEE_ADMIN_RO Employee Administrator (Read Only) The user assigned this role is considered a read-only auditor. The user can view but not add or edit employee records. N Y
N/A Employee Maintenance NOTE: This field is not supported. Y Y
EXP_APPROVER Expense Approver The user assigned this role can approve expense reports within an assigned group. N N
EXP_CASHADVANCE_ADMIN Expense Cash Advance Administrator The user assigned this role can view, issue, and manage cash advance requests. Y N
EXP_CARD_ADMIN Expense Company Card Administrator The user assigned this role can assign and unassign company cards, and map expense types to merchant category codes. Y N
EXP_CONFIG_ADMIN Expense Configuration Administrator This role is intended to be assigned to and used by SAP Concur internal staff only, with few exceptions. The user assigned this role can fully manage (add, edit, delete) Expense group configurations, Policies, Expense-based forms and fields, validations, and vendor lists, Expense report and authorized approver workflows, Audit rules, Expense types and expense categories, Payment types, Account codes, Exceptions, Car configuration and reimbursement, Receipt handling, including payment hold, scan configurations, receipt limits, and receipt imaging, Email reminders, Reimbursement currencies, Offline settings, Configuration change log (view only), Taxability and Deductibility Calculation Service.
NOTE: A user cannot be assigned the EXP_CONFIG_ADMIN and the EXP_CONFIG_ADMIN_RO.
Y N
EXP_CONFIG_ADMIN_RO Expense Configuration Administrator (Restricted) The user assigned this role can fully manage (add, edit, delete) vendor list items, authorized approvers, audit rules, account codes, exceptions, personal and company car rates, receipt handling including receipt limits, payment hold, and scan configurations, email reminders, configuration change log (view only), taxability and deductibility calculation service. Y N
EXP_PROCESSOR Expense Processor The user assigned this role can view and update expense reports within Expense Processor.
The Access for Processor field limits the reports the processor can view to all reports excluding returned reports, all reports including returned reports, or only reports pending processor step and beyond.
NOTE: The user should only be assigned one of the Expense Processor roles. If the user is assigned multiple Expense Processor roles, the role with the greatest level of access will be applied. The levels of access, from highest to lowest, are: Expense Processor Manager (1), Expense Processor (2), Expense Processor (Audit) (3).
Y N
EXP_PROCESSOR_AUDIT Expense Processor (Audit) The user assigned this role can view expense reports within Expense Processor.
NOTE: The user should only be assigned one of the Expense Processor roles. If the user is assigned multiple Expense Processor roles, the role with the greatest level of access will be applied. The levels of access, from highest to lowest, are: Expense Processor Manager (1), Expense Processor (2), Expense Processor (Audit) (3).
Y N
EXP_PROCESSOR_ADMIN Expense Processor Manager The user assigned this role can view, update, and delete expense reports within Expense Processor. The Access for Processor field limits the reports the processor can view all reports excluding returned reports, all reports including returned reports, or only reports pending processor step and beyond.
NOTE: The user should only be assigned one of the Expense Processor roles. If the user is assigned multiple Expense Processor roles, the role with the greatest level of access will be applied. The levels of access, from highest to lowest, are: Expense Processor Manager (1), Expense Processor (2), Expense Processor (Audit) (3).
Y N
EXP_PROXY_USER Expense Proxy Logon The user assigned this role can log on to Expense and act as a proxy user for other employees within an assigned group. Y N
EXP_RECEIPT_PROCESSOR Expense Receipt Processor The user assigned this role can update the receipt status for an expense report. N N
N/A Expense Type Administrator NOTE: This field is not supported. N N
EXP_USER Expense User The user assigned this role can create and submit expense reports and cash advances if those features are used by the user's company. N N
EXP_EMPLOYEE_ADMIN Employee Admin Permission on Expense Hierarchy Can grant Expense Hierarchy Nodes permission to users in the Employee Admin.
NOTE: Each user assigned Employee admin must also be assigned permissions for reporting (BI), expense, and payment (Invoice). These additional permissions govern the roles the employee administrator can assign for the employees in his or her assigned groups.
Y N
EXP_FIND_ATTENDEES_USER Employee (while finding attendees) Role code to determine the field access while searching attendees. N N
EXP_EXTRACT_ADMIN Extract Administrator Special role assigned by the SAP Concur Implementation department to clients who are transitioning from the Standard Edition to the Professional Edition. This role provides access to the File Export Configuration tool. N N
N/A Expense Processor(Concur Audit) NOTE: This field is not supported. N N
EXP_FB_TAX_ADMIN Fringe Benefits Tax Administrator Along with the Tax Administration role, the user assigned this role can manage fringe-benefit tax. N N
SHD_IMPORT_EXTRACT_ADMIN_RO Import/Extract Monitor (formerly Integration Administrator - Restricted) A user assigned this role can view details of import, extract, archive, and reporting consolidation jobs, job schedule, system logs. Depending on configuration, this user may also be able to upload import files, and download extract files. N Y
SHD_PASSWORD_ADMIN Password Manager The user assigned this role can update passwords for Expense users.
User will have read only access to the following fields on the User Details page in User Administration: Title, First Name, Middle Name, Nickname, Last Name, Suffix, and Email.
Preventing Access: A module property is available to restrict this role from changing password. Please contact SAP Concur directly to have the Password Access Restriction feature activated.
NOTE: The users with Expense and either Travel or Invoice have one password for all applications. When any of the Password Manager roles changes a password, it changes for all.
Y Y
EXP_REIMBURSEMENT_AUDITOR Reimbursement Auditor A user assigned this role can view Expense Pay functionality: Funding Accounts, Batch Configurations, Card Programs, Expense Pay Settings, Current and Historical Batch List, Daily Funding and Returned Amounts, Payment Demand List, Report Payees List, and Employee Banking Status N Y
EXP_REIMBURSEMENT_APPROVER Reimbursement Manager A user assigned this role can fully manage (add, edit, delete) Expense Pay functionality: Funding Accounts, Batch Configurations, Card Programs, and Expense Pay Settings.
In addition, a user assigned this role can view the following Expense Pay details: Current and Historical Batch List, Daily Funding and Returned Amounts, Payment Demand List, and Report Payees List.
Only global Reimbursement Managers can create and view payment demands: Employee Banking Status
Y Y
SHD_ROLE_ADMIN Role Administrator A user assigned this role is granted access to the Expense, Invoice, and Request tabs through User Permissions. Y Y
N/A Role Builder This role is intended to be assigned to and used by SAP Concur internal staff only. N Y
SHD_CONFIG_ADMIN Shared Configuration Administrator This role is intended to be assigned to and used by SAP Concur internal staff only, with few exceptions. The user assigned this role can fully manage (add, edit, delete) Feature hierarchies for Expense Reports and Vendor Invoices, Employee group configurations, including assignment of the employee form, Employee forms and fields, validations, and custom and connected lists, Expense and payment delegate configurations, Reimbursement currencies, Imaging settings, Accounting structure (ledgers), Localization tasks, Configuration change log (view only). Hierarchy segment values are used to identify the hierarchy node for which this employee has approval rights. If blank, resolves to the global group.
NOTE: A user cannot be assigned the SHD_CONFIG_ADMIN and the SHD_CONFIG_ADMIN_RO.
Y Y
SHD_CONFIG_ADMIN_RO Shared Configuration Administrator (Restricted) The user assigned this role can access locations (add or edit), view, add, edit, and delete custom list items, and view the configuration change log. Y Y
SHD_TAX_ADMIN Tax Administrator The user assigned this role can fully manage (add, edit, delete) value added tax (VAT) tax configurations, and rates. N N
SHD_TAX_ADMIN_RO Tax Administrator (Restricted) The user assigned this role can view tax configurations. N N
SHD_TRAINING_ADMIN Training Administrator The user assigned this role can access the Training Administration tool to configure client-preferred Training landing page and the contents and contact information that displays. N Y
N/A Travel and Expense Pilot User Do not use: this role is retired. N/A N/A
EXP_TRAVEL_AND_EXPENSE_USER Travel and Expense User NOTE: This field is not supported. N Y
N/A UI Preview NOTE: This field is not supported. N Y
SHD_WEB_SERVICES_ADMIN Web Services Administrator The user assigned this role can access the Partner Application Administration page to register or enable partner applications to access the company’s data using the SAP Concur web services. The partner applications are required for some integrations, and do not appear in the SAP Concur App Center. They may also access the Manage User Apps page to restrict the User applications in the SAP Concur App Center for their company's users, as well as Enable Enterprise partner applications within the SAP Concur App Center. N SAP Concur Connect

Request Product Roles

Role Code Role Full Name Description Group-Aware Product Area
SHD_DATA_RETENTION_ADMIN Data Retention Administrator The user assigned this role views and configures the data retention policy for the company and can hold and purge individual users. N Y
REQ_PROCESSOR_ADMIN Request Administrator This is one of the Request processor roles.
The user assigned this role can view and fully manage virtually all requests.
Y N
REQ_APPROVER Request Approver The user assigned this role can approve requests within their assigned group. N N
REQ_PROCESSOR_AUDIT Request Auditor This is one of the Request processor roles.
This is a read-only role. The SAP Concur client can assign this role to TMCs, to its own internal travel agent(s), or to any other user that needs read-only access to requests.
Y N
REQ_CONFIG_ADMIN Request Configuration Administrator This role is intended to be assigned to and used by SAP Concur internal staff only, with few exceptions.
The user assigned this role can fully manage (add, edit, delete) all request-related features on the Request Admin menu.
NOTE: A user cannot be assigned the REQ_CONFIG_ADMIN and the REQ_CONFIG_ADMIN_RO.
Y N
REQ_CONFIG_ADMIN_RO Request Configuration Administrator (restricted) The user assigned this role can fully manage (add, edit, delete) list management, locations, segment types, and travel agency offices Y N
REQ_EVENT_ADMIN Request Event Manager The user assigned this role can create a primary event request for multiple event attendees.
This role must be assigned with the Request Proxy Logon role.
N N
REQ_PROXY_USER Request Proxy Logon The user assigned this role can log on to Request and act as a proxy user for other employees within an assigned group. Y N
REQ_USER Request User The user assigned this role can create and submit requests. N N
REQ_RISK_ADMIN Risk Manager This permission appears only if Request is integrated with Concur Risk Management. The user assigned this role can process requests waiting for Risk Manager processing and view submitted requests with risk.
NOTE: A user cannot be assigned this role and one of the other Request processor roles.
Y N
REQ_PROCESSOR TMC Agent This is one of the Request processor roles.
The SAP Concur client assigns this role to one or more agents of its Travel Management Company (TMC) or to the client's internal travel agent(s). In some regions, it is appropriate for the TMC Agent to access the request after the user submits it but before the approver receives it. This way, the TMC Agent can add/edit the segment amounts – ensuring accuracy for the request approver.
Y N

Invoice (Payment) Product Roles

Role Code Role Full Name Description Group-Aware Product Area
SHD_BUDGET_ADMIN Budget Administrator The user assigned this role can configure the Fiscal Calendar, Budget Categories, Budget Tracking Fields, Budget Items, and Budget Settings. The Budget Administrator can see the budget amounts as configured in the Budget Items, but not the budget actuals as is shown in the dashboards. Budget Administrators have access to all budget items within an entity. N Y
SHD_BUDGET_APPROVER Budget Approver/Manager The user assigned this role can approve invoices, purchase requests, and expense reports and can view budgets in the budget dashboards. The Budget Approver does not have access to the budget configuration information. N Y
SHD_BUDGET_OWNER Budget Owner The user assigned this role owns the budget and can view budgets in the dashboards. The Budget Owner does not have access to the budget configuration information. N Y
SHD_BUDGET_VIEWER Budget Viewer The user assigned this role views budgets in the dashboards. There can be one or several budget viewers. The Budget Viewer does not have access to the budget configuration information. N Y
INV_PURCH_RECEIVER Central Receiver The user assigned this role can add, edit, and delete purchase order receipts and receipt images. However, they cannot transmit or process purchase orders or invoices. Y N
INV_IC_VERIFIER Client Managed Capture Verifier The user assigned this role can verify the output of invoices in the client-managed version of Capture Processing. N N
SHD_DATA_RETENTION_ADMIN Data Retention Administrator The user is assigned this role views and configures the data retention policy for the company and can hold and purge individual users. N Y
INV_EMPLOYEE_ADMIN Employee Admin Permission on Invoice Hierarchy The user assigned this role can grant Invoice Hierarchy Nodes permission to users in the Employee Admin.
NOTE: Each user assigned employee admin must also be assigned permissions for reporting (BI), expense, and payment (Invoice). These additional permissions govern the roles the employee administrator can assign for the employees in his or her assigned groups.
Y N
INV_AP_USER Invoice AP User The user assigned this role can create, assign, and reassign invoices. They can also reassign a different policy to an invoice and restore deleted invoices. Y N
INV_APPROVER Invoice Approver The user assigned this role can to approve invoices within an assigned group. N N
INV_CONFIG_ADMIN Invoice(Payment) Configuration Administrator This role is intended to be assigned to and used by SAP Concur internal staff only, with few exceptions.
The user assigned this role can fully manage (add, edit, delete) Invoice group configurations, Policies, Invoice-based forms, fields, and validations, Invoice and authorized approver workflows, Audit rules, Expense types, Account codes and account code hierarchy, Exceptions, Image handling, including scan configurations, invoice imaging, vendor imaging, Email reminders, Company Info, Configuration change log (view only).
NOTE: A user cannot be assigned the INV_CONFIG_ADMIN and the INV_CONFIG_ADMIN_RO.
Y N
INV_CONFIG_ADMIN_RO Invoice (Payment) Configuration Administrator (Restricted) The user assigned this role can fully manage (add, edit, delete) authorized approvers, audit rules, account codes, exceptions, expense types, scan configurations, email reminders, and configuration change log (view only). Y N
N/A Invoice Full User NOTE: This field is not supported. N N
N/A Invoice Pilot User NOTE: This field is not supported. N N
INV_PMT_MANAGER Invoice Payment Manager A user assigned this role can fully manage (add, edit, delete) Invoice Pay functionality. This user can monitor and adjust Invoice Pay batches and invoices scheduled for payment and define the Checking and ACH funding accounts that are used for payment. N N
INV_IMAGE_PROCESSOR Invoice Image Processor The user assigned this role can update the status of receipt and invoice images. N N
INV_PROCESSOR Invoice(Payment) Processor The user assigned this role an view and update invoices within Invoice Processor. They may also assign or reassign invoices, and restore deleted invoices.
NOTE: The user should only be assigned one of the Invoice Processor roles. If the user is assigned multiple Invoice Processor roles, the role with the least level of access will be applied. The levels of access, from highest to lowest, are: Invoice Processor Manager (1), Invoice Processor (2), Invoice Processor (Audit) (3)
Y N
INV_PROCESSOR_AUDIT Invoice(Payment) Processor (Audit) The user assigned this role can view invoices within Invoice Processor.
NOTE: A user cannot be assigned the Processor Audit role and any other Invoice (Payment) processor role.
Y N
INV_PROCESSOR_MANAGER Invoice(Payment) Processor Manager The user assigned this role can view, update, and delete invoices within Invoice Processor.
NOTE: A user cannot be assigned the Invoice (Payment) Processor Manager role and an audit role.
Y N
INV_PROXY_USER Invoice(Payment) Proxy Logon The user assigned this role can log on to Vendor Invoices and act as a proxy user for other employees within an assigned group. Y N
INV_PURCH_USER Invoice Purchasing User The user assigned this role cannot create and submit invoices but can be granted rights to change form field values to adjust totals, etc. in Invoice Purchase Order.
NOTE: This role is available only to users of Invoice.
N N
INV_RECEIPT_PROCESSOR Invoice(Payment) Receipt Processor The user assigned this role can view and update invoices in Invoice Received status within Invoice Processor. Y N
INV_TAX_ADMIN Invoice Tax Administrator The user assigned this role can configure and activate the Tax Administration tool. N N
INV_PMT_USER Invoice User The user assigned this role can create and submit invoices. N N
INV_VENDOR_ADMIN Invoice Vendor Manager The user assigned this role can work with vendors, including approving new vendors, working with the master list, and mapping vendors. Y N
INV_PURCH_ORDER_PROCESSOR Purchase Order Processor The user assigned this role can process purchase orders in the Purchase Request module. Y N
INV_PURCH_ORDER_PROCESSOR_AUDIT Purchase Order Processor (Audit) The user assigned this role can view purchase orders within the purchase order processor and can view receipts within the purchase order processor. receipts. Y N
INV_PURCH_REQ_APPROVER Purchase Request Approver The user assigned this role can approve purchase requests in the Purchase Request module. N N
INV_PURCH_REQ_PROCESSOR Purchase Request Processor The user assigned this role can process purchase requests in the Purchase Request module. Y N
INV_PURCH_REQ_PROCESSOR_AUDIT Purchase Request Processor (Audit) The user assigned this role can view purchase requests within the purchase request processor. Y N
INV_PURCH_REQ_PROXY_USER Purchase Request Proxy Logon The user assigned this role can log on to Purchase Request and act as a proxy user for other employees within an assigned group.
NOTE: This role may proxy for any user assigned the Purchase Request User role.
Y N
INV_PURCH_REQ_USER Purchase Request User The user assigned this role can create purchase requests in the Purchase Request module. N N
INV_RECEIPT_USER Receipt User The user assigned this role can enter, update, and delete receipt data for their own purchase orders. N N

Reporting Product Roles

Role Code Role Full Name Description Group-Aware Product Area
BUDGET_REPORTING_USER Budget Role for Cognos The user assigned this role can access the Budget module in the Analysis/Intelligence data model. Y N
REPORTING_CAS_ANALYST CAS Analyst NOTE: Do not use. This role is retired. Y N
REPORTING_BUSINESS_AUTHOR Cognos Business Author The user assigned this role can use Analysis/Intelligence to view data for reports submitted at all hierarchical levels within their assigned groups (as well as any data not group-related). The user is assigned the Business license type, which restricts the features to which they have access. They may also run existing reports, create new reports or modify existing basic reports using the basic tool, Query Studio.
NOTE: A user cannot be assigned this role and the Cognos Professional Author or Cognos Consumer roles, only one of these three may be assigned.
Y N
REPORTING_CONSUMER Cognos Consumer The user assigned this role can use Analysis/Intelligence to view data for reports submitted at all hierarchical levels within their assigned groups (as well as any data not group-related). The user is assigned the Consumer license type, which further restricts the features to which they have access. They may also run existing reports, with read-only access.
NOTE: A user cannot be assigned this role and the Cognos Professional Author or Cognos Business Author roles, only one of these three may be assigned.
Y N
REPORTING_PRO_AUTHOR Cognos Professional Author The user assigned this role can use Analysis/Intelligence to view data for reports submitted at all hierarchical levels (no group assignment required). The user is assigned the Professional license type, which allows access to all features. They may also run existing reports, create new reports or modify existing basic reports using the basic tool, Query Studio, and create new reports or modify existing basic reports using the advanced tool, Report Studio. They can also schedule automatic report runs. Y N
REPORTING_CONFIG_ADMIN Consolidation Configuration Administrator This role is used by companies using the Reporting Database that wish to consolidate the data from the current version and previous versions.
The user assigned this role can map expense types and custom fields to a single consolidated definition, and adjust other consolidation settings.
NOTE: This role does not include access to Analysis/Intelligence.
N N
REPORTING_HIST_DATA_USER Cognos Hist Data Access Cognos Hist Data Access. N N
REPORTING_DASHBOARD_USER Dashboard User NOTE: Do not use. This role is retired. N N
REPORTING_EMPLOYEE_ADMIN Employee Admin Permission on Reporting Hierarchy The user assigned this role can grant Reporting Hierarchy Nodes permission to users in the Employee Admin.
NOTE: Each user assigned Employee admin must also be assigned permissions for reporting (BI), expense, and payment (Invoice). These additional permissions govern the roles the employee administrator can assign for the employees in his or her assigned groups.
Y N

Travel Extension v4

Important: This API is currently in pre-release status and is only available to approved early access participants. The API is under development and might change before being generally released. To become an early access participant, contact your SAP Concur Representative.

This endpoint is available to clients and partners who utilize User Provisioning v4 to provision or modify users in the Concur Travel extension. It allows callers to retrieve values for the Concur Travel user that have been provisioned via User Provisioning. For partners or TMCs who need to retrieve additional Travel Profile data that is not supported here, please use Travel Profile v2 API.

Limitations: This API is only available to partners who have been granted access by SAP Concur. Access to this documentation does not provide access to the API.

Products and Editions

Scope Usage

Name Description Endpoint
travel.user.general.read Reads general data. GET
travel.user.private.read Reads private data. GET

Dependencies

SAP Concur clients must use the User Provisioning v4 API to provision users in order to use this endpoint to retrieve user data.

Access Token Usage

This API supports only company access tokens.

Retrieve Travel User Data

Retrieves the information of a SAP Concur Travel user.

Scopes

Request

URI

Template
GET /travel/v4/Users
Parameters
Name Type Format Description
id string UUID The SAP Concur UUID of the user.

Headers

Response

Status Codes

Headers

Example

Request

GET https://www.us.api.concursolutions.com/travel/v4/Users

Response

    {
    "id": "e83e6c1a-f4f2-456a-921e-cc8be49a2715",
    "urn:ietf:params:scim:schemas:extension:travel:2.0:User":
    {
        "ruleClass": {
            "name": "RC_1",
            "id": 972
        },
        "travelCrsName": "",
        "xmlProfileSyncId": "",
        "travelNameRemark": "",
        "orgUnit": Development,
        "customFields": [],
        "manager": "c2f98467-361e-446b-8b36-65e47c222605",
        "groups": [
            64165
        ]
    }
    }

Schema

Travel Extension

Name Type Format Description
ruleClass complex - Required Assigns the Concur Travel rule class for the travel user. Either Rule Class ID or Rule Class Name should be provided. Value must exactly match Travel Class name maintained in Travel.
travelNameRemark string - Concur Travel name remark. Can be used by TMCs to distinguish profiles where companies have multiple users with the same name.
xmlProfileSyncId string - A user-assigned Concur Travel user identifier that allows the user profile to be synchronized with other vendors. The following characters cannot be used as a value for this record: # ! * & ( ) ~ ' { - ^ } / ? > < , ; : " + = ] %
travelCrsName string - The name of the profile in the GDS system or GDS profile name. This value associates a Concur Travel profile to the GDS profile.
orgUnit string - Org unit for the user. Value must exactly match an Org unit or division value setup for the company.
groups integer - List of user groups that user belongs to for assigning travel roles.
manager complex - Travel approver of this user. Must match an existing employee in the travel database.
customFields complex - User can set values to custom data fields.

Error

Name Type Format Description
errorCode string - Required Machine readable code associated with the error.
errorMessage string - Required Message associated with the error.

USER

User

The Users resource represents a set of SAP Concur users. It is always managed as a batch of users, even if the batch contains only one user.

Version

1.0

Process Flow

Process Flow for the User Resource

Retrieve a User's Information

This resource allows you to get profile information for a given user. If a request URL does not include a ?loginID parameter then the response will be for the logged in user (and you must pass authentication information with your request).

GET api/user/v1.0/user

Parameters

Name Type Format Description
loginID string - The URL-encoded SAP Concur login of the user. Optional.

Get User Response Schema

Name Type Format Description
loginID string - The user's login ID.
Active Boolean Y/N Whether the user is currently active.
FirstName string - The user's first name.
LastName string - The user's last name.
Mi string - The user's middle initial.
EmailAddress string - The user's email address.
EmpId string - The unique identifier for the user.
LedgerName string - The user's assigned account code ledger.
LocaleName string - The user's language locale code. One of the Supported Locales. Example: United States English is en_US.
OrgUnit1 through OrgUnit6 string - Varies depending on configuration.
Custom1 through Custom21 string - Varies depending on configuration. If the custom field is a list field, the data will be returned as: (list item short code) list item name. List Field Example: (1234) Project 1234
CtryCode string 2-character country code The user's two-digit country code.
CashAdvanceAccountCode string - The user's account code for cash advances.
CrnCode string ISO 4217 currency code The user's three character reimbursement currency. Example: United States Dollar is USD.
CtrySubCode string - The user's two-digit country code and two-digit state or province code. Example: Washington State, United States is US-WA.
ExpenseUser Boolean Y/N Whether the user has access to Expense.
ExpenseApprover Boolean Y/N Whether the user is an Expense approver.
TripUser Boolean Y/N Whether the user has access to Travel.
InvoiceUser Boolean Y/N Whether the user has access to Invoice.
InvoiceApprover Boolean Y/N Whether the user is an Invoice approver.
ExpenseApproverEmployeeID string - The employee ID of the user's Expense approver. If you are importing both a user and their approver, the approver should be listed before the user in the batch.
IsTestEmp Boolean Y/N Whether the user is a test user.

Retrieve All Users Based on Search Criteria

Note that this is a version 3.0 API and can be found here.

Retrieve the List of Required Fields for Creating a User

Retrieves a list of configured fields on the Global employee form in SAP Concur.

GET api/user/v1.0/FormFields

Required Fields Response Schema

Name Type Format Description
Id string - The unique field identifier.
Label string - The displayed field label.
ControlType string - The type of field.
DataType string - The type of data the field collects.
MaxLength string - The maximum length of data in the field.
Required string - Whether the field is required.
Cols string - The number of columns the field occupies.
Access string - The end-user access to the field.
Width string - The width of the field, in pixels.
Custom string - Whether the field is custom.
Sequence string - The sequence of the field on the form.

These elements are returned for Custom fields only:

Name Type Format Description
ParentFormTypeCode string - This element is only populated for multi-level list fields. The type of form that the parent field (the field one level higher in the list hierarchy) is connected to.
ParentFieldId string - The identifier for the field one level higher in the list hierarchy.
IsCopyDownSourceForOtherForms string - Whether the field is used as a copy down source by other forms.
ListName string - The name of the list associated with the field.
HierLevel string - The list level of the field. If it is the second level field in a two-level list, the value would be 2.

Update a User's Account Information

Updates one or more users. The batch can contain up to 500 users.

NOTE: The User API can be used to add new users, however the user accounts will not be fully configured and ready for use. Additional work to the user profiles must be completed, either with manual edits or updates via the user import, in order to complete the user profiles. There is a high degree of variability in customer configuration that is not all supported by this API. Manual edits or updates via a file import are most likely required to complete the User profiles started with this API. Only POST is supported. Please use the Employee Import feature if the User API does not meet your needs.

POST api/user/v1.0/users

This API requires as its arguments a batch element containing a UserProfile child element for each user to be added (in the future) or updated. The UserProfile child elements will vary depending on the form configuration, and may contain the following elements.

Update User Account Information Request Schema

Name Type Format Description
EmpId string - Required. The unique identifier for the user. The default value is the user's email address. Maximum 48 characters.
FeedRecordNumber string - Required. The record number in the current batch.
LoginId string - Required. The user's login ID. The default value is the user's email address. The value MUST have a '@'. Maximum 128 characters.
LocaleName string - The user's language locale code. List of locale codes are available in the Employee Import Appendix. One of the Supported Locales. Example: United States English is en_US. The supported languages vary by company but always include en_US. Maximum: 5 characters.
Active Boolean Y/N Whether the user is currently active.
Password string - Required. The user's password. This element can be used to enter the password for a new user, but cannot be used to update the password for an existing user. Maximum 255 characters.
FirstName string - The user's first name. Maximum 32 characters.
LastName string - The user's last name. Maximum 32 characters.
Mi string - The user's middle initial. Maximum 1 character.
EmailAddress string - The user's email address. Maximum 255 characters.
LedgerKey string - Required for new users. The user's assigned account code ledger. Example: Default. Maximum 20 characters.
OrgUnit1 through OrgUnit6 string - The custom organizational unit fields on the Employee form. Varies depending on configuration. Use the Employee Form Field resource to get the list of configured fields. Maximum 48 characters for each field.
Custom1 through Custom21 string - The custom fields on the Employee form. Varies depending on configuration. Use the Employee Form Field resource to get the list of configured fields. Maximum 48 characters.
CtryCode string ISO 3166-1 alpha-2 country code Country code, example: United States is US. Maximum 2 characters.
CashAdvanceAccountCode string - The user's account code for cash advances. Maximum 20 characters.
CrnKey string ISO 4217 3-letter currency code Currency code for the user's reimbursement currency. Example: United States Dollar is USD. Maximum 3 characters.
CtrySubCode string - The user's two-character country code and two-character state or province code. Example: Washington State, United States is US-WA. Maximum 2 characters.
ExpenseUser Boolean Y/N Whether the user has access to Expense.
ExpenseApprover Boolean Y/N Whether the user is an Expense approver.
TripUser Boolean Y/N Whether the user has access to Travel.
InvoiceUser Boolean Y/N Whether the user has access to Invoice.
InvoiceApprover Boolean Y/N Whether the user is an Invoice approver.
ExpenseApproverEmployeeID string - The employee ID of the user's Expense approver. If you are importing both a user and their approver, the approver should be listed before the user in the batch. Maximum 48 characters.
NewLoginID string - Use this element to change the Login ID for an existing employee. Maximum 128 characters.
NewEmployeeID string - Use this element to change the Employee ID for an existing employee. Maximum 48 characters.

Update User Account Information Response Schema

Name Type Format Description
records-succeeded string - The number of records processed that were successfully added or updated.
records-failed string - The number of records processed that were not successfully added or updated.

When any users are successfully updated:

The request will return the UserDetails parent element with a UserInfo element for each successfully added or updated user. The UserInfo elements will contain the following child elements:

Name Type Format Description
EmployeeID string - The employee ID of the user.
FeedRecordNumber string - The item number of the record in the feed.
Status string - The status of the attempt to add or update the user. Should always contain the word SUCCESS.

When any users fail:

The request will return the errors parent element with an error parent element for each record failure. The error element will contain the following child elements:

Name Type Format Description
EmployeeID string - The employee ID of the user.
FeedRecordNumber string - The item number of the record in the feed.
Message string - The error message.

Example

<batch xmlns="http://www.concursolutions.com/api/user/2011/02">
    <UserProfile>
        <LoginID>loginID</LoginID>
        <EmployeeID>employeeID</EmployeeID>
        <Active>N</Active>
        <--! Any more required fields -->
    </UserProfile>
</batch>

Update a User's Password

POST api/user/v1.0/Users/password

Updates passwords for up to 500 users.

Please keep in mind that this method will not update the user password expiry date, if you are updating the password to overcome password expiration policy. User will still have to change his password when they login to SAP Concur if the original password before update was expired.

Update User's Password Request Schema

This function requires as its arguments a UserBatch element containing a User child element for each user. The User element must have the following elements:

Name Type Format Description
LoginID string - Required. The user's login ID. The default value is the user's email address. The value MUST contain '@'.
Password string - The user's new password.

Update User's Password Response Schema

This request will return a BatchResult parent element with the following child elements:

Name Type Format Description
RecordsSucceeded string - The number of records processed that were successfully updated.
RecordsFailed string - The number of records processed that were not successfully updated.
UserPasswordStatusList string - This parent element will contains a UserPasswordStatus element for each user.

The UserPasswordStatus element contains the following child elements:

Name Type Format Description
LoginID string - The login ID of the user.
Status Boolean Success/Failed The status of the attempt to update the user's password.
Message string - Additional details about the success or failure of the request.

Example

<UserBatch xmlns="http://www.concursolutions.com/api/user/2011/02">
    <User>
        <LoginID>loginID</LoginID>
        <Password>password</Password>
    </User>
</UserBatch>